Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Version bump and readme update for v2.0.0 (#166)
* Version bump and readme update for v2.0.0 * Update to README. * Added note about OpenStack. * Moved documentation into romana repo. * Small change in link to doc. * Direct link to kubernetes README.
- Loading branch information
Showing
16 changed files
with
726 additions
and
59 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,48 +1,55 @@ | ||
| # The Romana Project | ||
|
|
||
| *** | ||
|
|
||
| ## _Welcome to the Romana 2.0 preview release!_ | ||
|
|
||
| _Romana provides cloud native, beautifully simple and natively routed network_ | ||
| _traffic for Kubernetes clusters._ | ||
|
|
||
| _You are viewing the source repository of the Romana 2.0 preview release,_ | ||
| _which brings many improvements:_ | ||
|
|
||
| * _Ability to create large Kubernetes clusters across multiple availability_ | ||
| _zones in AWS, without the need to create overlay networks, and without any_ | ||
| _limitation imposed by AWS VPC's 50 route limit._ | ||
| * _Topology aware IPAM with improved, more efficient IP address and route management._ | ||
| * _Improvements to Romana's internal architecture._ | ||
| * _Ability to be deployed on top of kops clusters._ | ||
|
|
||
| _If you would like to jump straight to the Romana 2.0 specific installation_ | ||
| _instructions, please click [here](docs/kubernetes)._ | ||
|
|
||
| *** | ||
|
|
||
| Romana is a network and security automation solution for Cloud Native | ||
| applications. Romana automates the creation of isolated Cloud Native Networks | ||
| and secures applications with a distributed firewall that applies access | ||
| control policies consistently across all endpoints and services, wherever they | ||
| run. | ||
| # Romana - network and security automation solution for cloud native applications | ||
|
|
||
| Romana is a network and security automation solution for cloud native | ||
| applications. | ||
|
|
||
| * Romana automates the creation of isolated cloud native networks | ||
| and secures applications with a distributed firewall that applies access | ||
| control policies consistently across all endpoints (pods or VMs) and | ||
| services, wherever they run. | ||
| * Through Romana's topology aware IPAM, endpoints receive natively routable | ||
| addresses: No overlays or tunnels are required, increasing performance | ||
| and providing operational simplicity. | ||
| * Because IP addresses are assigned with network topology in mind, routes | ||
| within the network are highly aggregated, reducing the impact on networking | ||
| hardware, and allowing more secure configurations. | ||
| * Supports Kubernetes and OpenStack clusters, on premise or on AWS. | ||
|
|
||
| # Installation | ||
|
|
||
| To get started with Romana on Kubernetes, go [here](docs/kubernetes/README.md). | ||
|
|
||
| For OpenStack installations, please contact us by email or on Slack. | ||
|
|
||
| We are working on more detailed documentation to cover all the features and | ||
| installation methods. Reach out to the team via email, Slack or GitHub if you | ||
| need some help in the meantime. | ||
|
|
||
| # Additional documentation | ||
|
|
||
| * [Romana core concepts and terminology](docs/romana/README.md): Find out how | ||
| Romana is different and how it accomplishes simplified routing for endpoints. | ||
| * [Romana's topology configuration](docs/romana/TOPOLOGY.md): Explanation and | ||
| examples of how to configure Romana for different networking environments. | ||
| * [Romana VIPs](docs/romana/VIPS.md): External IPs for Kubernetes clusters, | ||
| managed by Romana with automatic failover. | ||
| * [Romana DNS](docs/romana/DNS.md): How to setup DNS for Romana VIPs. | ||
| * [Romana network policies](docs/romana/POLICIES.md): Introduction to Romana | ||
| network policies. | ||
| * [Romana route publisher](docs/romana/ROUTE_PUBLISHER.md): In routed L3 | ||
| networks, the route publisher announces the necessary routes either via BGP | ||
| or OSPF. | ||
|
|
||
| # Code | ||
|
|
||
| This repository contains the installer and documentation. The Romana source | ||
| code, however, is contained in the [core](https://github.com/romana/core) | ||
| repository. | ||
|
|
||
| # Installation | ||
|
|
||
| We're updating all of our documentation for installing and using Romana. | ||
| To get started with Romana on Kubernetes, go [here](docs/kubernetes). | ||
| This repository contains the documentation and installation tools for the Romana project. | ||
| You can find the application code in the [core](https://github.com/romana/core) repository. | ||
|
|
||
| And get in touch with us via email, Slack or GitHub if you need some help in the meantime. | ||
| Latest stable release: 2.0 | ||
|
|
||
| # Contact Us | ||
|
|
||
| * By email: [info@romana.io](mailto:info@romana.io) | ||
| * On the [Romana Slack](https://romana.slack.com/). You'll need to email to request an invite to this slack network | ||
| * On the [Romana Slack](https://romana.slack.com/). Please request an invite | ||
| by email. | ||
| * On GitHub, just open an [issue](https://github.com/romana/romana/issues/new) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| # Romana DNS | ||
|
|
||
| Romana DNS adds DNS support for Romana VIPs. It is drop in replacement for | ||
| kube-dns. | ||
|
|
||
| ## Installtion steps | ||
|
|
||
| ### On Master node of kubernetes cluster | ||
|
|
||
| * Make a note on number of replicas for kube-dns using following command: | ||
| ``` | ||
| echo `kubectl get deploy -n kube-system kube-dns -o jsonpath="{.spec.replicas}"` | ||
| ``` | ||
| * Now set replicas for kube-dns to zero using following command: | ||
| ``` | ||
| kubectl scale deploy -n kube-system kube-dns --replicas=0 | ||
| ``` | ||
| * Wait till kube-dns replicas are zero (around a minute or so) | ||
|
|
||
| ### On All nodes i.e master and compute nodes of the kubernetes cluster | ||
|
|
||
| * Remove earlier docker images and replace it romana one using commands below: | ||
| ``` | ||
| docker rmi gcr.io/google_containers/k8s-dns-kube-dns-amd64:1.14.5 | ||
| docker pull pani/romanadns | ||
| docker tag pani/romanadns:latest gcr.io/google_containers/k8s-dns-kube-dns-amd64:1.14.5 | ||
| ``` | ||
| * Now return back to master node for further commands | ||
|
|
||
| ### On Master node of kubernetes cluster | ||
|
|
||
| * Now assuming you had 2 replicas before, from first step above, we restore the replica count for kube-dns as follows: | ||
| ``` | ||
| kubectl scale deploy -n kube-system kube-dns --replicas=2 | ||
| ``` | ||
| * Wait for a minute or so for the pod to come up and we have romanaDNS up and running. | ||
|
|
||
| ## Testing | ||
|
|
||
| * Run dig to see if dns is working properly using command: | ||
| ``` | ||
| dig @10.96.0.10 +short romana.kube-system.svc.cluster.local | ||
| ``` | ||
| * Download this sample [nginx](files/nginx.yml) yaml file and then use following command to create an nginx service with RomanaIP in it: | ||
| ``` | ||
| kubectl create -f nginx.yml | ||
| ``` | ||
| * This should create and load nginx service with RomanaIP, which should reflect in the dig result below: | ||
| ``` | ||
| dig @10.96.0.10 +short nginx.default.svc.cluster.local | ||
| ``` | ||
|
|
||
| ### Sample Results | ||
| ``` | ||
| $ dig @10.96.0.10 +short romana.kube-system.svc.cluster.local | ||
| 10.96.0.99 | ||
| 192.168.99.10 | ||
| $ dig @10.96.0.10 +short nginx.default.svc.cluster.local | ||
| 10.116.0.0 | ||
| 10.99.181.64 | ||
| 192.168.99.101 | ||
| ``` | ||
|
|
||
| *** |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # Romana network policies | ||
|
|
||
| ## Introduction | ||
|
|
||
| Romana allows the fine grained control and management of network traffic via network policies. The Romana network policies format was inspired by the Kubernetes network policy specification. However, Romana policies can be applied in Kubernetes as well as OpenStack environments. Furthermore, Romana extends the policies with additional features, such as the ability to control network traffic not only for containers or VMs, but also for bare metal servers. | ||
|
|
||
| ### Overview | ||
|
|
||
| Network policies are defined as small JSON snippets, specifying match characteristics for network traffic. Essentially, network policies firewall rules definitions. Details and examples will be given below. | ||
|
|
||
| These policy definitions are sent to the Romana Policy service using this service's RESTful API. The service validates those policies and forwards them to the Romana agent on each host of the cluster. There, the policies are translated to iptables rules, which are then applied to the kernel. | ||
|
|
||
| ### Tools and integration | ||
|
|
||
| After installing an OpenStack or Kubernetes cluster with Romana, the `romana` command line tool can be used to specify and list policies. However, Romana provides a specific integration for Kubernetes. This allows the operator to use standard Kubernetes policies and policy APIs, should they wish to do so. Romana picks up those Kubernetes policies, seamlessly translates them to Romana policies and then applies them as necessary. | ||
|
|
||
| For OpenStack, or if policies need to be applied to bare metal servers, the Romana Policy API or command line tools are used directly. | ||
|
|
||
|
|
||
| ## Policy definition format | ||
|
|
||
| Each Romana network policy document contains a single top-level element (`securitypolicies`), which itself is a list of individual policies. A policy contains the following top-level elements: | ||
|
|
||
| * **name:** The name of the policy. You can refer to policies by name or an automatically generated unique ID. Oftentimes names are much easier to remember. Therefore, it is useful to make this a short, descriptive and - if possible - unique ID. | ||
| * **description:** A line of text, which can serve as human readable documentation for this policy. | ||
| * **direction:** Determines whether the policy applies packets that are incoming (ingress) to the endpoint or outgoing (egress) from the endpoint. Currently, the only permissible value for this field is `ingress`. This means that the policy rules describe traffic travelling TO the specified (see `applied_to`) target. | ||
| * **applied_to:** A list of specifiers, defining to whom the rules are applied. Typically a tenant/segment combo or a CIDR. | ||
| * **peers:** A list of specifiers, defining the 'other side' of the traffic. In case of ingress traffic, this would be the originator of the packets. The peer may be defined as "any", which serves as a wildcard. | ||
| * **rules:** A list of traffic type specifications, usually consisting of protocol and ports. | ||
|
|
||
|
|
||
| ``` | ||
| { | ||
| "securitypolicies": [{ | ||
| "name": <policy-name>, | ||
| "description": <policy-description>, | ||
| "direction": "ingress", | ||
| "applied_to": [<applied-spec-1>, <applied-spec-2>, ...], | ||
| "peers": [<peer-spec-1>, <peer-spec-2>, ...], | ||
| "rules": [<traffic-spec-1>, <traffic-spec-2>, ...] | ||
| }] | ||
| } | ||
| ``` | ||
| Example: | ||
| ``` | ||
| { | ||
| "securitypolicies": [{ | ||
| "name": "policy1", | ||
| "description": "Opening SSH, HTTP and HTTPS ports as well as ICMP", | ||
| "direction": "ingress", | ||
| "applied_to": [{ | ||
| "tenant": "admin", | ||
| "segment": "default" | ||
| }], | ||
| "peers": [{ | ||
| "peer": "any" | ||
| }], | ||
| "rules": [ | ||
| { | ||
| "protocol": "tcp", | ||
| "ports": [22, 80, 443] | ||
| }, | ||
| { | ||
| "protocol": "icmp" | ||
| } | ||
| ] | ||
| }] | ||
| } | ||
| ``` | ||
|
|
||
| *** | ||
|
|
Oops, something went wrong.