diff --git a/1.10/networking/load-balancing-vips/virtual-networks.md b/1.10/networking/load-balancing-vips/virtual-networks.md deleted file mode 100644 index 428e046eb..000000000 --- a/1.10/networking/load-balancing-vips/virtual-networks.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -post_title: Virtual Networks -feature_maturity: preview -menu_order: 20 ---- - -DC/OS enables virtual networking through the use of virtual networks. DC/OS virtual networks enable you to provide each container in the system with a unique IP address (“IP-per-container”) with isolation guarantees amongst subnets. DC/OS virtual networks offer the following advantages: - -* Both Mesos and Docker containers can communicate from within a single node and between nodes on a cluster. -* Services can be created such that their traffic is isolated from other traffic coming from any other virtual network or host in the cluster. -* They remove the need to worry about potentially overlapping ports in applications, or the need to use nonstandard ports for services to avoid overlapping. -* You can generate any number of instances of a class of tasks and have them all listen on the same port so that clients don’t have to do port discovery. -* You can run applications that require intra-cluster connectivity, like Cassandra, HDFS, and Riak. -* You can create multiple virtual networks to isolate different portions of your organization, for instance, development, marketing, and production. - -**Note:** Isolation guarantees among subnets depend on your CNI implementation and/or your firewall policies. - -# Using Virtual Networks - -First, you or the data center operator needs to [configure the virtual networks](/docs/1.10/networking/virtual-networks/). - -Virtual networks are configured at install time. You or the data center operator will specify a canonical name for each network in the `config.yaml`. When your service needs to launch a container, refer to it by that canonical name. - -To use an virtual network in a Marathon app definition, specify the `"network": "USER"` property along with an `ipAddress` field in the form: `{"ipAddress": {"network": "$MYNETWORK"}}`. The value of `$MYNETWORK` is the canonical name of the network. - -# Example - -The following Marathon application definition specifies a network named `dcos-1`, which refers to the target DC/OS virtual network of the same name. - -```json -{ - "id":"my-networking", - "cmd":"env; ip -o addr; sleep 30", - "cpus":0.10, - "mem":64, - "instances":1, - "backoffFactor":1.14472988585, - "backoffSeconds":5, - "ipAddress":{ - "networkName":"dcos-1" - }, - "container":{ - "type":"DOCKER", - "docker":{ - "network":"USER", - "image":"busybox", - "portMappings":[ - { - "containerPort":123, - "servicePort":80, - "name":"foo" - } - ] - } - } -} -``` - -Learn more about ports and networking in [Marathon](/docs/1.10/deploying-services/service-ports/). diff --git a/1.10/networking/load-balancing/east-west/index.md b/1.10/networking/load-balancing/east-west/index.md new file mode 100644 index 000000000..16b80ba54 --- /dev/null +++ b/1.10/networking/load-balancing/east-west/index.md @@ -0,0 +1,4 @@ +--- +post_title: East-West Load Balancer +menu_order: 10 +--- diff --git a/1.10/networking/load-balancing/east-west/minuteman/index.md b/1.10/networking/load-balancing/east-west/minuteman/index.md new file mode 100644 index 000000000..ba437f1e5 --- /dev/null +++ b/1.10/networking/load-balancing/east-west/minuteman/index.md @@ -0,0 +1,4 @@ +--- +post_title: Minuteman +menu_order: 00 +--- diff --git a/1.10/networking/load-balancing-vips/index.md b/1.10/networking/load-balancing/index.md similarity index 98% rename from 1.10/networking/load-balancing-vips/index.md rename to 1.10/networking/load-balancing/index.md index 37aba35b5..47b76c198 100644 --- a/1.10/networking/load-balancing-vips/index.md +++ b/1.10/networking/load-balancing/index.md @@ -1,5 +1,5 @@ --- -post_title: Load Balancing and Virtual IPs (VIPs) +post_title: Load Balancing menu_order: 00 --- @@ -46,4 +46,4 @@ Port 61420 must be open for the load balancer to work correctly. Because the loa ## Next steps - [Assign a VIP to your application](/docs/1.10/networking/load-balancing-vips/virtual-ip-addresses/) -- [Learn about the implementation details](https://github.com/dcos/minuteman) \ No newline at end of file +- [Learn about the implementation details](https://github.com/dcos/minuteman) diff --git a/1.10/networking/load-balancing/north-south/edge-lb/architecture.md b/1.10/networking/load-balancing/north-south/edge-lb/architecture.md new file mode 100644 index 000000000..42883f8db --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/architecture.md @@ -0,0 +1,62 @@ +--- +post_title: Edge-LB Architecture +menu_order: 60 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +Edge-LB has a 3-part architecture (API Server, Pool, and Load Balancer) that +is run entirely on top of DC/OS. + +# Glossary + +## Edge-LB + +The entire component (API Server, Pool, and Load Balancer). + +## Edge-LB API Server + +The service that responds to CLI commands and manages Pools. + +## Edge-LB Pool + +The unit of Load Balancer configuration within Edge-LB. The Load Balancers within the same Pool are identical. + +The Pool is concerned with properties such as the number of instances of the Load Balancers and their placement. + +The number of instances of Load Balancers *cannot be scaled down* (This is +a limitation that we plan to address). + +## Edge-LB Load Balancer + +The individual instances of the load balancer software (e.g. HAProxy). These accept traffic and route it to the appropriate services within the DC/OS cluster. + +# Edge-LB Load Balancer Reload Behavior + +## Normal Reload Scenario + +A change to an service (such as scaling up or down) that is load balanced +by a Pool will trigger a reload of its Load Balancers. This reload has +the following properies: + +* No traffic is dropped (unless the service instance that was serving the + request was killed). +* The Load Balancer will wait until existing connections terminate, so a long + running connection will prevent the reload from completing. +* A reload will occur at most once every 10 seconds. + +The properties of this reload enable strategies such as +[Blue/Green Deployment](/1.10/networking/edge-lb/strategies#blue-green-deployment). + +## Load Balancer Relaunch Scenario + +A change to the Load Balancer (such as adding a Secret) will trigger a +relaunch of all such Load Balancers within the same Pool. This relaunch has +the following properies: + +* Traffic is dropped + * To minimize the impact, we suggest running more than one Load + Balancer within the Pool. +* The Load Balancer will be relaunched on the same node (unless the node itself + has failed). diff --git a/1.10/networking/load-balancing/north-south/edge-lb/auth.md b/1.10/networking/load-balancing/north-south/edge-lb/auth.md new file mode 100644 index 000000000..c22e0cb70 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/auth.md @@ -0,0 +1,96 @@ +--- +post_title: Configuring DC/OS Access for Edge-LB +menu_order: 10 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +This topic describes how to configure DC/OS access for Edge-LB. Depending on your [security mode](/1.10/overview/security/security-modes/), Edge-LB may require [service authentication](/1.10/security/ent/service-auth/) for access to DC/OS. + +| Security mode | Service Account | +|---------------|-----------------------| +| Disabled | Not available | +| Permissive | Recommended (optional) | +| Strict (not currenly supported) | Required | + +**Prerequisites:** + +- [DC/OS CLI installed](/1.10/cli/install/) and be logged in as a superuser. +- [Enterprise DC/OS CLI 0.4.14 or later installed](/1.10/cli/enterprise-cli/#ent-cli-install). +- If your [security mode](/1.10/overview/security/security-modes/) is `permissive`, you must [get the root cert](/1.10/networking/tls-ssl/get-cert/) before issuing the curl commands in this section. + +# Create a Key Pair +In this step, a 2048-bit RSA public-private key pair is created using the Enterprise DC/OS CLI. + +Create a public-private key pair and save each value into a separate file within the current directory. + +```bash +dcos security org service-accounts keypair .pem .pem +``` + +**Tip:** You can use the [DC/OS Secret Store](/1.10/security/ent/secrets/) to secure the key pair. + +# Create a Service Account + +## Permissive +From a terminal prompt, create a new service account (``) containing the public key (`.pem`). + +```bash +dcos security org service-accounts create -p .pem -d "Edge-LB service account" +``` + +**Tip:** You can verify your new service account using the following command. + +```bash +dcos security org service-accounts show +``` + +# Create a Secret +Create a secret (`edge-lb/`) with your service account (``) and private key specified (`.pem`). + +**Tip:** If you store your secret in a path that matches the service name (e.g. service name and path are `edge-lb`), then only the service named `edge-lb` can access it. + +## Permissive + +```bash +dcos security secrets create-sa-secret .pem edge-lb/ +``` + +**Tip:** +You can list the secrets with this command: + +```bash +dcos security secrets list / +``` + +# Create and Assign Permissions +Use the following curl commands to rapidly provision the Edge-LB service account with the required permissions. + +**Tips:** + +- Any `/` character in a resource must be replaced with `%252F` before it can be passed in a curl command. +- When using the API to manage permissions, you must first create the permission and then assign it. Sometimes, the permission may already exist. In this case, the API returns an informative message. You can regard this as a confirmation and continue to the next command. + +1. Create the permission. + + ## Permissive + + ```bash + dcos security org users grant service-account-id dcos:service:marathon:marathon:services create --description "Allows access to any service launched by the native Marathon instance" + + dcos security org users grant service-account-id dcos:service:marathon:marathon:admin:events create --description "Allows access to Marathon events" + ``` + +1. Grant the permissions and the allowed actions to the service account using the following commands. + + ## Permissive + Run these commands. + + ```bash + dcos security org users grant service-account-id dcos:service:marathon:marathon:services:%252F/users/edgelb-principal read + + dcos security org users grant service-account-id dcos:service:marathon:marathon:admin:events/users/edgelb-principal read + ``` + +For more information about the available Edge-LB commands, see the [Edge-LB command reference](/1.10/cli/command-reference/dcos-edgelb/). diff --git a/1.10/networking/load-balancing/north-south/edge-lb/configuration.md b/1.10/networking/load-balancing/north-south/edge-lb/configuration.md new file mode 100644 index 000000000..8d6979031 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/configuration.md @@ -0,0 +1,624 @@ +--- +post_title: Edge-LB Configuration +menu_order: 30 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +# Swagger Specification + +The specification below describes all possible configuration options. The majority of fields have sensible defaults and should be modified with caution. Use the tool at [swagger.io](http://editor.swagger.io/) to render this document in Swagger. + +Consult the [Quickstart Guide](/1.10/networking/edge-lb/quickstart) for an example of a real-life Edge-LB configuration. + +See the [Examples](/1.10/networking/edge-lb/examples) for more common use cases. + +## Edge-LB v0.1.7 + +This information can also be found by running `dcos edgelb config --reference` + +```yaml +swagger: '2.0' +definitions: + Config: + type: object + description: >- + * If a default is not set, then it will be left empty, even for objects. + * Set defaults in the object that is furthest from the root object. + * Always set a default for arrays. + * The purpose of "x-nullable" is to allow the output JSON field to be set + to the golang "zero value". Without "x-nullable", the field will be + removed altogether from the resulting JSON. + * Actual validation is done in the code, not expressed in swagger. + * Since an empty boolean is interpreted as "false", don't set + a default. + * CamelCase + * Swagger will only do enum validation if it is a top level definition! + default: { "pools": [] } + properties: + pools: + type: array + description: The array of pools. + items: + $ref: '#/definitions/Pool' + Pool: + type: object + description: >- + The pool contains information on resources that the pool needs. Changes + make to this section will relaunch the tasks. + default: + { + "namespace": "dcos-edgelb/pools", + "packageName": "edgelb-pool", + "packageVersion": "stub-universe", + "role": "slave_public", + "cpus": 0.9, + "cpusAdminOverhead": 0.1, + "mem": 992, + "memAdminOverhead": 32, + "disk": 256, + "count": 1, + "constraints": "hostname:UNIQUE", + "ports": [], + "secrets": [], + "virtualNetworks": [], + "haproxy": {} + } + properties: + name: + type: string + description: The pool name. + namespace: + type: string + description: The DC/OS space (sometimes also referred to as a "group"). + x-nullable: true + packageName: + type: string + packageVersion: + type: string + role: + type: string + description: >- + Mesos role for load balancers. Defaults to "slave_public" so that + load balancers will be run on public agents. Use "*" to run load + balancers on private agents. Read more about Mesos roles at + http://mesos.apache.org/documentation/latest/roles/ + cpus: + type: number + cpusAdminOverhead: + type: number + mem: + type: integer + description: "Memory requirements (in MB)" + format: int32 + memAdminOverhead: + type: integer + description: "Memory requirements (in MB)" + format: int32 + disk: + type: integer + description: "Disk size (in MB)" + format: int32 + count: + type: integer + x-nullable: true + format: int32 + description: 'Number of load balancer instances in the pool.' + constraints: + type: string + x-nullable: true + description: 'Marathon style constraints for load balancer instance placement.' + ports: + type: array + description: >- + Override ports to allocate for each load balancer instance. + Defaults to {{haproxy.frontend.objs[].bindPort}} and + {{haproxy.stats.bindPort}}. + Use this field to pre-allocate all needed ports with or + without the frontends present. For example: [80, 443, 9090]. + If the length of the ports array is not zero, only the + ports specified will be allocated by the pool scheduler. + items: + type: integer + format: int32 + secrets: + type: array + description: DC/OS secrets. + items: + type: object + properties: + secret: + description: Secret name + type: string + file: + description: >- + File name. + + The file "myfile" will be found at "$SECRETS/myfile" + type: string + environmentVariables: + type: object + description: >- + Environment variables to pass to tasks. + + Prefix with "ELB_FILE_" and it will be written to a file. For example, + the contents of "ELB_FILE_MYENV" will be written to + "$ENVFILE/ELB_FILE_MYENV". + additionalProperties: + type: string + autoCertificate: + type: boolean + description: >- + Autogenerate a self-signed SSL/TLS certificate. It is not generated + by default. + + It will be written to "$AUTOCERT". + virtualNetworks: + type: array + description: Virtual networks to join. + items: + type: object + properties: + name: + description: The name of the virtual network to join. + type: string + labels: + description: Labels to pass to the virtual network plugin. + additionalProperties: + type: string + haproxy: + $ref: '#/definitions/Haproxy' + Haproxy: + type: object + default: + { + "stats": {}, + "frontends": [], + "backends": [] + } + properties: + stats: + $ref: '#/definitions/Stats' + frontends: + description: 'Array of frontends.' + type: array + items: + $ref: '#/definitions/Frontend' + backends: + description: 'Array of backends.' + type: array + items: + $ref: '#/definitions/Backend' + Stats: + type: object + default: + { + "bindAddress": "0.0.0.0", + "bindPort": 9090 + } + properties: + bindAddress: + type: string + bindPort: + type: integer + format: int32 + Frontend: + type: object + description: >- + The Frontend maps to the HAProxy frontend. This includes + information such as what addresses and ports to listen on, what + SSL/TLS certificates to use, and which backends to route to. + default: + { + "bindAddress": "0.0.0.0", + "bindPort": -1, + "certificates": [], + "miscStrs": [], + "linkBackend": {} + } + properties: + name: + description: 'Defaults to frontend_{{bindAddress}}_{{bindPort}}.' + type: string + bindAddress: + description: >- + Only use characters that are allowed in the frontend name. Known + invalid frontend name characters include "*", "[", and "]". + type: string + bindPort: + description: >- + The port (e.g. 80 for HTTP or 443 for HTTPS) that this frontend will + bind to. + type: integer + x-nullable: true + format: int32 + bindModifier: + description: "Additional text to put in the bind field" + type: string + certificates: + type: array + items: + description: >- + SSL/TLS certificates in the load balancer. + + For secrets, use "$SECRETS/my_file_name" + For environment files, use "$ENVFILE/my_file_name" + For autoCertificate, use "$AUTOCERT" + type: string + redirectToHttps: + type: object + default: { "except": [] } + description: >- + Setting this to the empty object is enough to redirect all traffic + from HTTP (this frontend) to HTTPS (port 443). + properties: + except: + type: array + description: >- + One may additionally set a whitelist of fields that must be + matched to allow HTTP. + items: + type: object + description: "Boolean AND will be applied with every selected value" + properties: + host: + type: string + description: "Match on host" + pathBeg: + type: string + description: "Match on path" + miscStrs: + description: "Additional template lines inserted before use_backend" + type: array + items: + type: string + protocol: + description: >- + The frontend protocol is how clients/users communicate with HAProxy. + $ref: '#/definitions/Protocol' + linkBackend: + type: object + description: >- + This describes what backends to send traffic to. This can be expressed + with a variety of filters such as matching on the hostname or the + HTTP URL path. + default: { "map": [] } + properties: + defaultBackend: + type: string + description: >- + This is default backend that is routed to if none of the other + filters are matched. + map: + type: array + description: >- + This is an optional field that specifies a mapping to various + backends. These rules are applied in order. + items: + type: object + description: >- + "backend" and at least one of the condition fields + must be filled out. If multiple conditions are filled out they + will be combined with a boolean "AND". + properties: + backend: + type: string + hostEq: + description: "All lowercase." + type: string + hostReg: + description: >- + All lowercase. It is possible for a port (e.g. "foo.com:80") + to be in this regex! + type: string + pathBeg: + type: string + pathEnd: + type: string + pathReg: + type: string + Backend: + type: object + default: + { + "miscStrs": [], + "servers": [], + "balance": "roundrobin", + "rewriteHttp": {} + } + properties: + name: + type: string + description: This is name that frontends refer to. + protocol: + description: >- + The backend protocol is how HAProxy communicates with the + servers it's load balancing. + $ref: '#/definitions/Protocol' + rewriteHttp: + description: >- + Manipulate HTTP headers. There is no effect unless the protocol is + either HTTP or HTTPS. + $ref: '#/definitions/RewriteHttp' + balance: + description: 'Load balancing strategy. e.g. roundrobin, leastconn, etc.' + type: string + customCheck: + type: object + description: 'This is used to specify alternate forms of healthchecks' + properties: + httpchk: + type: boolean + httpchkMiscStr: + type: string + sslHelloChk: + type: boolean + miscStr: + type: string + miscStrs: + description: "Additional template lines inserted before servers" + type: array + items: + type: string + servers: + description: 'Array of backend network sources / selectors.' + type: array + items: + $ref: '#/definitions/Server' + RewriteHttp: + type: object + default: + { + "request": {}, + "response": {} + } + properties: + host: + description: "Set the host header value" + type: string + path: + type: object + description: >- + Rewrite the HTTP URL path. All fields required, otherwise it's + ignored. + properties: + fromPath: + type: string + toPath: + type: string + request: + $ref: '#/definitions/RewriteHttpRequest' + response: + $ref: '#/definitions/RewriteHttpResponse' + sticky: + type: object + default: { "enabled": true } + description: >- + Sticky sessions via a cookie. + + To use the default values (recommended), set this field to the + empty object. + properties: + enabled: + type: boolean + x-nullable: true + customStr: + type: string + RewriteHttpRequest: + description: >- + Rewrite the request. + + To use the default values (recommended), set this field to the + empty object. + type: object + default: + { + "forwardfor": true, + "xForwardedPort": true, + "xForwardedProtoHttpsIfTls": true, + "setHostHeader": true, + "rewritePath": true + } + properties: + forwardfor: + type: boolean + x-nullable: true + xForwardedPort: + type: boolean + x-nullable: true + xForwardedProtoHttpsIfTls: + type: boolean + x-nullable: true + setHostHeader: + type: boolean + x-nullable: true + rewritePath: + type: boolean + x-nullable: true + RewriteHttpResponse: + description: >- + Rewrite the response. + + To use the default values (recommended), set this field to the + empty object. + type: object + default: + { "rewriteLocation": true } + properties: + rewriteLocation: + type: boolean + x-nullable: true + Server: + type: object + default: + { + "type": "AUTO_IP", + "framework": {}, + "task": {}, + "check": {}, + "port": {} + } + properties: + type: + $ref: '#/definitions/ServerType' + framework: + type: object + description: >- + The Mesos framework. If unsure, the value should probably be + "marathon". + default: { "match": "EXACT" } + properties: + value: + type: string + match: + $ref: '#/definitions/Match' + task: + type: object + default: { "match": "EXACT" } + properties: + value: + description: >- + The Task name. This field is not needed for VIPs. + For Marathon pods this is the container name NOT the pod name. + type: string + match: + $ref: '#/definitions/Match' + check: + type: object + default: + { "enabled": true } + description: >- + Enable health checks. These are by default TCP health checks. For + more options see "customCheck". + + These are required for DNS resolution (and hence VIPs) to function + properly. + properties: + enabled: + type: boolean + x-nullable: true + customStr: + type: string + port: + $ref: '#/definitions/ServerPort' + miscStr: + description: Append arbitrary string to the "server" directive. + type: string + ServerPort: + type: object + properties: + name: + description: >- + The name of the port. This is used for AUTO_IP, AGENT_IP and + CONTAINER_IP. + type: string + all: + description: >- + For AUTO_IP, AGENT_IP and CONTAINER_IP this + can be used to expose all defined ports. + + This should only be used if a name is not defined + for the port and there is a single port defined for the service. + type: boolean + vip: + description: 'Set the VIP definition directly (e.g. "/myvip:1234").' + type: string + Protocol: + type: string + enum: + - HTTP + - HTTPS + - TCP + - TLS + ServerType: + description: >- + AUTO_IP detects between AGENT_IP and CONTAINER_IP and uses the + appropriate value. + + AGENT_IP is for HOST and BRIDGE networking. VIP for l4lb service + addresses. CONTAINER_IP is for virtual networks. This is not DNS. + type: string + enum: + - AUTO_IP + - AGENT_IP + - CONTAINER_IP + - VIP + Error: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + Match: + type: string + enum: + - EXACT + - REGEX +``` + +# Configuration format + +Edge-LB accepts configuration in YAML or JSON, but YAML is preferred for readability. + +A helpful graphical visualization tool for swagger can be found at [editor.swagger.io](http://editor.swagger.io) + +# SSL/TLS certificates + +See the [Examples](/1.10/networking/edge-lb/examples#sample-certificates). + +# Configuration format FAQ + +## How do I convert YAML to JSON? + +`dcos edgelb config --to-json=/path/to/json` + +## How do I convert JSON to YAML? + +There currently isn't an automated way to do this, the suggested method is to +hand convert it, and then use the YAML to JSON conversion on your YAML and +then do a diff between your YAML and the JSON. + +``` +# First hand convert JSON to YAML + +# Then compare to original json with the `diff` shell command. +# Here we "convert" even the JSON file to get consistently formatted JSON +diff <(dcos edgelb config --to-json=myconfig.yaml) <(dcos edgelb config --to-json=myconfig.json) +``` + +## How do I create an empty object in YAML? + +The syntax is the same as in JSON. For example, basic use of `sticky` +involves setting it to the empty object. + +YAML: +``` + sticky: {} +``` + +JSON: +``` +{ + "sticky": {} +} +``` + +## Where does JSON expect commas? + +Put them everywhere except after the last element in an object or array. + +``` +{ + "key1": "value1", + "key2": "value2" +} +``` + +``` +{ + "key": ["value1", "value2"] +} +``` diff --git a/1.10/networking/load-balancing/north-south/edge-lb/examples.md b/1.10/networking/load-balancing/north-south/edge-lb/examples.md new file mode 100644 index 000000000..cb306a71a --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/examples.md @@ -0,0 +1,209 @@ +--- +post_title: Edge-LB Examples +menu_order: 60 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +# SSL/TLS Certificate Usage + +This example demonstrates 3 different ways to get and use a certificate: + +- Automatically generated self-signed certificate. +- DC/OS Secrets. +- (Insecure) Environment variables. + +```yaml +--- +pools: + - name: sample-certificates + count: 1 + autoCertificate: true + secrets: + - secret: mysecret + file: mysecretfile + environmentVariables: + ELB_FILE_HAPROXY_CERT: | + -----BEGIN CERTIFICATE----- + foo + -----END CERTIFICATE----- + -----BEGIN RSA PRIVATE KEY----- + bar + -----END RSA PRIVATE KEY----- + haproxy: + frontends: + - bindPort: 443 + protocol: HTTPS + certificates: + - $AUTOCERT + linkBackend: + defaultBackend: host-httpd + - bindPort: 444 + protocol: HTTPS + certificates: + - $SECRETS/mysecretfile + linkBackend: + defaultBackend: host-httpd + - bindPort: 445 + protocol: HTTPS + certificates: + - $ENVFILE/ELB_FILE_HAPROXY_CERT + linkBackend: + defaultBackend: host-httpd + backends: + - name: host-httpd + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: host-httpd + port: + name: web +``` + +# HTTP/HTTPS URL Path Routing + +This example sets the following HTTP/HTTPs paths: + +- `http:///` - The `default-svc` service. +- `http:///foo` - The `foo-svc` service. +- `http:///bar` - The `bar-svc` service. + +```yaml +--- +pools: + - name: sample-path-routing + count: 1 + haproxy: + frontends: + - bindPort: 80 + protocol: HTTP + linkBackend: + defaultBackend: backend-default + map: + - pathBeg: /foo + backend: backend-foo + - pathBeg: /bar + backend: backend-bar + backends: + - name: backend-foo + protocol: HTTP + rewriteHttp: + # The paths specified here means that "foo-svc" will see + # traffic coming in at "/" rather than at "/foo" + path: + fromPath: /foo + toPath: / + servers: + - framework: + value: marathon + task: + value: foo-svc + port: + name: foo-port + - name: backend-bar + protocol: HTTP + rewriteHttp: + # The paths specified here means that "bar-svc" will see + # traffic coming in at "/" rather than at "/bar" + path: + fromPath: /bar + toPath: / + servers: + - framework: + value: marathon + task: + value: bar-svc + port: + name: bar-port + - name: backend-default + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: default-svc + port: + name: default-port +``` + +# HTTP/HTTPS Virtual Host (VHost) Routing + +This example sets the following VHost routes: + +- `http://foo.example.com` - The `foo-svc` service. +- `http://bar.example.com` - The `bar-svc` service. + +```yaml +--- +pools: + - name: sample-vhost-routing + count: 1 + haproxy: + frontends: + - bindPort: 80 + protocol: HTTP + linkBackend: + map: + - hostEq: foo.example.com + backend: backend-foo + - hostEq: bar.example.com + backend: backend-bar + backends: + - name: backend-foo + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: foo-svc + port: + name: foo-port + - name: backend-bar + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: bar-svc + port: + name: bar-port +``` + +# HTTP Healthcheck + +All services have TCP healthchecks enabled by default. + +This example customizes the healthcheck in the following ways: +- Enables HTTP healthcheck. +- HTTP healthcheck does a HTTP `GET` request on `/health/check/endpoint`. + +```yaml +--- +pools: + - name: sample-health-check + count: 1 + haproxy: + frontends: + - bindPort: 80 + protocol: HTTP + linkBackend: + defaultBackend: backend-default + backends: + - name: backend-default + protocol: HTTP + customCheck: + httpchk: true + # More on configuring httpchkMiscStr: + # https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#option%20httpchk + httpchkMiscStr: GET /health/check/endpoint + servers: + - framework: + value: marathon + task: + value: default-svc + port: + name: default-port +``` diff --git a/1.10/networking/load-balancing/north-south/edge-lb/index.md b/1.10/networking/load-balancing/north-south/edge-lb/index.md new file mode 100644 index 000000000..5a33281c7 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/index.md @@ -0,0 +1,11 @@ +--- +post_title: Edge-LB +menu_order: 2 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +Edge-LB proxies and load balances traffic to all services that run on DC/OS. + +Edge-LB is built on HAProxy. HAProxy provides base functionality, such as load balancing for TCP and HTTP-based applications, SSL support, and health checking. On top of this, Edge-LB provides first class support for zero downtime service deployment strategies, such as blue/green deployment. Edge-LB subscribes to Mesos and updates HAProxy configuration in real time. diff --git a/1.10/networking/load-balancing/north-south/edge-lb/installing.md b/1.10/networking/load-balancing/north-south/edge-lb/installing.md new file mode 100644 index 000000000..0e5b8fbf9 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/installing.md @@ -0,0 +1,68 @@ +--- +post_title: Installing Edge-LB +menu_order: 0 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +Edge-LB is installed as a remote DC/OS package. After you add the remote Edge-LB repository, you can install Edge-LB with the following command from the DC/OS CLI: + +``` +dcos package install edgelb +``` + +**Important:** Edge-LB is not yet supported in strict [security mode](/1.10/overview/security/security-modes/). + +**Prerequisites:** + +- [DC/OS CLI installed](/1.10/cli/install/) and be logged in as a superuser. +- Access to [the remote Edge-LB repositories](https://support.mesosphere.com/hc/en-us/articles/213198586). +- Depending on your [security mode](/1.10/overview/security/security-modes/), you may be able to configure Edge-LB with [service authentication](/1.10/security/ent/service-auth/) before installing and using with DC/OS, allowing you to control what actions your service can take on your cluster. For information on how to configure service authentication for Edge-LB, see the [documentation](/1.10/networking/edge-lb/auth). + + | Security mode | Service Account | + |---------------|-----------------------| + | Disabled | Not available | + | Permissive | Recommended (Optional) | + | Strict (not currently supported) | Required | + +# Add Edge-LB package repositories +Contact your sales representative or sales@mesosphere.io for access to this repository. Edge-LB is not available in the default Universe repository. + +# Create a configuration file for service authentication +If you have configured service authentication (recommended), you must create a JSON options file with your credentials. This file will be passed to DC/OS when you install Edge-LB. + +In the file, specify the service account (``) and secret (`edge-lb/`) that you created earlier. + +```json +{ + "service": { + "principal": "", + "secret_name": "edge-lb/" + } +} +``` + +Save the file with a meaningful name, such as .json. + +# Install Edge-LB +Install Edge-LB with this command: + +```bash +dcos package install --options=.json edgelb +``` + +Run this command and wait for the Edge-LB service to be ready. + +```bash +until dcos edgelb ping; do sleep 1; done +``` + +You should receive this message when ready: + +```bash +pong +``` + +- For more information about configuring Edge-LB, see the [Edge-LB Configuration](/1.10/networking/edge-lb/configuration) section. +- For more information about the available Edge-LB commands, see the [Edge-LB Command Reference](/1.10/cli/command-reference/dcos-edgelb/). diff --git a/1.10/networking/load-balancing/north-south/edge-lb/quickstart.md b/1.10/networking/load-balancing/north-south/edge-lb/quickstart.md new file mode 100644 index 000000000..642ceaeeb --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/quickstart.md @@ -0,0 +1,142 @@ +--- +post_title: Edge-LB Quickstart +menu_order: 20 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +In this quickstart you will create an [Edge-LB pool](/1.10/networking/edge-lb/architecture#edge-lb-pool), a sample service to load balance, and then access this service through [Edge-LB](/1.10/networking/edge-lb/architecture#edge-lb). + +**Prerequsites:** + +- Edge-LB [installed and running](/1.10/networking/edge-lb/installing/). + +# Quickstart + +1. Create a [pool](/1.10/networking/edge-lb/architecture#edge-lb-pool) configuration. Copy the following configuration into a file named `sample-minimal.yaml`. + + ```yaml + --- + pools: + - name: sample-minimal + count: 1 + haproxy: + frontends: + - bindPort: 80 + protocol: HTTP + linkBackend: + defaultBackend: host-httpd + backends: + - name: host-httpd + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: host-httpd + port: + name: web + ``` + This is a minimal configuration. There are more complex configurations in the [Examples section](/1.10/networking/edge-lb/examples). All configuration options are documented in the [Configuration section](/1.10/networking/edge-lb/configuration). + +1. Upload the configuration to [Edge-LB](/1.10/networking/edge-lb/architecture#edge-lb). This will create a [pool](/1.10/networking/edge-lb/architecture#edge-lb-pool) with 1 [load balancer](/1.10/networking/edge-lb/architecture#edge-lb-load-balancer) instance that will run on the public agent nodes. + + ```bash + dcos edgelb config sample-minimal.yaml + ``` + +1. Create the service to load balance. Copy the following into a file named `host-httpd.json` + + ```json + { + "id": "/host-httpd", + "cmd": "/start $PORT0", + "instances": 1, + "cpus": 0.1, + "mem": 32, + "container": { + "type": "DOCKER", + "docker": { + "image": "nlsun/httpd" + } + }, + "portDefinitions": [ + { + "name": "web", + "protocol": "tcp", + "port": 0 + } + ], + "healthChecks": [ + { + "portIndex": 0, + "path": "/", + "protocol": "HTTP" + } + ] + } + ``` + +1. Deploy the sample service. + + ```bash + dcos marathon app add host-httpd.json + ``` + +1. Once the service has deployed, you can access the `host-httpd` service at `http:///` + + You can find the private IP(s) (that DC/OS was configured with) of the node(s) that the [Edge-LB load balancers](/1.10/networking/edge-lb/architecture#edge-lb-load-balancer) are running on with the following command: + ``` + dcos edgelb pool status sample-minimal --ip-only + ``` + + You can then use this information to determine the public IP that you would like to use to access the [load balancer](/1.10/networking/edge-lb/architecture#edge-lb-load-balancer). + +# Other commands + +1. Get agent information about running [load balancers](/1.10/networking/edge-lb/architecture#edge-lb-load-balancer): + + ```bash + dcos edgelb pool lb sample-minimal edgelb-pool-0 + ``` + + Your output should resemble this: + + ```bash + ... + { + "containerStatus": { + ... + "networkInfos": [ + { + ... + "ipAddresses": [ + { + ... + "ipAddress": "10.0.6.138" + } + ] + } + ] + }, + "executorId": { + "value": "edgelb-pool__fe58bc1d-ea3b-4d80-b703-828144d02374" + }, + "slaveId": { + "value": "a4b62ed1-88cf-4e3d-bd8a-19cc8fc10ac0-S2" + }, + "state": "TASK_RUNNING", + "taskId": { + "value": "edgelb-pool-0-server__fbae1265-f51e-48c9-8162-c09fe19b657d" + }, + "taskName": "edgelb-pool-0-server" + } + ``` + +# Next steps + +- For more Edge-LB configuration examples, see the [Examples section](/1.10/networking/edge-lb/examples). +- For more information about configuring Edge-LB, see the [edgelb configuration](/1.10/networking/edge-lb/configuration). + +- Consult the [dcos edgelb command reference](/1.10/cli/command-reference/dcos-edgelb/). diff --git a/1.10/networking/load-balancing/north-south/edge-lb/release-notes.md b/1.10/networking/load-balancing/north-south/edge-lb/release-notes.md new file mode 100644 index 000000000..8824b7c48 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/release-notes.md @@ -0,0 +1,26 @@ +--- +post_title: Edge-LB Release Notes +menu_order: 70 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +# v0.1.7 + +* Minimum DC/OS version 1.10 in universe package +* Fix static VIP parsing in template +* Fix bug with stale API server template artifacts + +# v0.1.6 + +* Fix Mesos Role `*` in config + +# v0.1.5 + +* Fix HTTP healthchecks +* Upgrade to HAProxy 1.7.6 + * HAProxy 1.7.3 had a bug that caused timeouts to occur upon each reload +* Make Virtual Networks configurable +* Fix bug with multiple Secrets +* Add dcos edgelb config --reference diff --git a/1.10/networking/load-balancing/north-south/edge-lb/strategies.md b/1.10/networking/load-balancing/north-south/edge-lb/strategies.md new file mode 100644 index 000000000..5b06b09d1 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/strategies.md @@ -0,0 +1,200 @@ +--- +post_title: Edge-LB Service Deployment Strategies +menu_order: 40 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +# Blue/Green Deployment + +A blue/green deployment is a method of achieving zero downtime by running +two versions of the same service (a "blue" and a "green" version) +and having the load balancer switch between the two. + +The idea is to have 2 fully scaled versions of the service so that if +something goes wrong with one, it can be quickly be switched to the other by +simply adjusting the load balancer. + +### Use Case: Service Upgrade + +1. The "web-server" service has "blue" and "green" versions that are running and + the load balancer is routing traffic successfully to "blue". +1. The Edge-LB configuration is updated to route traffic to "green" and + errors start occurring in the "green" service's logs. +1. The deployment is quickly rolled back by reverting Edge-LB to the original + configuration. + +## Prerequisites + +* Edge-LB CLI is installed. + + ``` + dcos package install edgelb --cli + ``` + +* Enough capacity on the DC/OS cluster for 2 fully deployed services. + +## Example Deployment + +Here, we use the example Edge-LB configuration from the quickstart and modify +it to load balance "svc-blue". + +`sample-minimal.yaml`: + +```yaml +--- +pools: + - name: sample-minimal + count: 1 + haproxy: + frontends: + - bindPort: 80 + protocol: HTTP + linkBackend: + defaultBackend: svc + backends: + - name: svc + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: svc-blue + port: + name: web +``` + +Here, we make a copy of the example service and rename it to "svc-blue". + +`svc-blue.json`: + +```json +{ + "id": "/svc-blue", + "cmd": "/start $PORT0", + "instances": 1, + "cpus": 0.1, + "mem": 32, + "container": { + "type": "DOCKER", + "docker": { + "image": "nlsun/httpd" + } + }, + "portDefinitions": [ + { + "name": "web", + "protocol": "tcp", + "port": 0 + } + ], + "healthChecks": [ + { + "portIndex": 0, + "path": "/", + "protocol": "HTTP" + } + ] +} +``` + +Here, we make another copy of the example service and rename it to "svc-green". + +`svc-green.json`: + +```json +{ + "id": "/svc-green", + "cmd": "/start $PORT0", + "instances": 1, + "cpus": 0.1, + "mem": 32, + "container": { + "type": "DOCKER", + "docker": { + "image": "nlsun/httpd" + } + }, + "portDefinitions": [ + { + "name": "web", + "protocol": "tcp", + "port": 0 + } + ], + "healthChecks": [ + { + "portIndex": 0, + "path": "/", + "protocol": "HTTP" + } + ] +} +``` + +1. First, upload the configuration to Edge-LB. + + ``` + dcos edgelb config sample-minimal.yaml + ``` + +1. Next, start the service "svc-blue". + + ```bash + dcos marathon svc add svc-blue.json + ``` + +1. Now, "svc-blue" is exposed at `http:///`. +1. Next, we begin our blue/green deployment and we deploy service "svc-green". + + ```bash + dcos marathon svc add svc-green.json + ``` + +1. Once `svc-green` is up and healthy, modify the Edge-LB configuration to point to `svc-green` + by changing: + + ```yaml + task: + value: svc-blue + ``` + + to: + + ```yaml + task: + value: svc-green + ``` + + so the end result is: + + ```yaml + --- + pools: + - name: sample-minimal + count: 1 + haproxy: + frontends: + - bindPort: 80 + protocol: HTTP + linkBackend: + defaultBackend: svc + backends: + - name: svc + protocol: HTTP + servers: + - framework: + value: marathon + task: + value: svc-green + port: + name: web + ``` +1. Upload the modified configuration to Edge-LB. + + ``` + dcos edgelb config sample-minimal.yaml + ``` + +1. Now, "svc-green" is exposed at `http:///`. diff --git a/1.10/networking/load-balancing/north-south/edge-lb/uninstalling.md b/1.10/networking/load-balancing/north-south/edge-lb/uninstalling.md new file mode 100644 index 000000000..b2a13ac17 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/edge-lb/uninstalling.md @@ -0,0 +1,29 @@ +--- +post_title: Uninstalling Edge-LB +menu_order: 50 +post_excerpt: "" +feature_maturity: "" +enterprise: 'yes' +--- + +*Do not* use the UI or CLI (Marathon) to create or destroy services managed by +Edge-LB. Operations *must performed exclusively through the Edge-LB CLI*. + +1. Delete each [pool](/1.10/networking/edge-lb/architecture#edge-lb-pool) (and each [load balancer](/1.10/networking/edge-lb/architecture#edge-lb-load-balancer) within it) with this command: + + ```bash + dcos edgelb pool delete + ``` + +1. Uninstall the [Edge-LB API server](/1.10/networking/edge-lb/architecture#edge-lb-api-server) + + ```bash + dcos package uninstall edgelb + ``` + +1. Remove the Universe repositories with these commands: + + ```bash + dcos package repo remove edgelb-aws + dcos package repo remove edgelb-pool-aws + ``` diff --git a/1.10/networking/load-balancing/north-south/index.md b/1.10/networking/load-balancing/north-south/index.md new file mode 100644 index 000000000..6727c4f49 --- /dev/null +++ b/1.10/networking/load-balancing/north-south/index.md @@ -0,0 +1,10 @@ +--- +post_title: North-South Load Balancers +menu_order: 00 +--- + +DC/OS Enterprise provides two north-south load balancing options out-of-the-box: Edge-LB and Marathon-LB. + +# Edge-LB versus Marathon-LB + +Edge-LB proxies and load balances traffic to _all_ services that run on DC/OS. In contrast, Marathon-LB can only load balance Marathon tasks. For example, if you are using Cassandra, Edge-LB can load balance the tasks launched by Cassandra. Consider using Edge-LBif you need to load balance non-Marathon tasks, or a combination of Marathon and non-Marathon tasks. Consider Marathon-LB if you need to balance only Marathon tasks. diff --git a/1.10/networking/marathon-lb/advanced.md b/1.10/networking/load-balancing/north-south/marathon-lb/advanced.md similarity index 100% rename from 1.10/networking/marathon-lb/advanced.md rename to 1.10/networking/load-balancing/north-south/marathon-lb/advanced.md diff --git a/1.10/networking/marathon-lb/index.md b/1.10/networking/load-balancing/north-south/marathon-lb/index.md similarity index 100% rename from 1.10/networking/marathon-lb/index.md rename to 1.10/networking/load-balancing/north-south/marathon-lb/index.md diff --git a/1.10/networking/marathon-lb/marathon-lb-advanced-tutorial.md b/1.10/networking/load-balancing/north-south/marathon-lb/marathon-lb-advanced-tutorial.md similarity index 100% rename from 1.10/networking/marathon-lb/marathon-lb-advanced-tutorial.md rename to 1.10/networking/load-balancing/north-south/marathon-lb/marathon-lb-advanced-tutorial.md diff --git a/1.10/networking/marathon-lb/marathon-lb-basic-tutorial.md b/1.10/networking/load-balancing/north-south/marathon-lb/marathon-lb-basic-tutorial.md similarity index 100% rename from 1.10/networking/marathon-lb/marathon-lb-basic-tutorial.md rename to 1.10/networking/load-balancing/north-south/marathon-lb/marathon-lb-basic-tutorial.md diff --git a/1.10/networking/marathon-lb/usage.md b/1.10/networking/load-balancing/north-south/marathon-lb/usage.md similarity index 100% rename from 1.10/networking/marathon-lb/usage.md rename to 1.10/networking/load-balancing/north-south/marathon-lb/usage.md diff --git a/1.10/networking/dns-overview.md b/1.10/networking/service-discovery/dns-overview.md similarity index 100% rename from 1.10/networking/dns-overview.md rename to 1.10/networking/service-discovery/dns-overview.md diff --git a/1.10/networking/service-discovery/index.md b/1.10/networking/service-discovery/index.md new file mode 100644 index 000000000..0bf63e871 --- /dev/null +++ b/1.10/networking/service-discovery/index.md @@ -0,0 +1,4 @@ +--- +post_title: Service Discovery +menu_order: 30 +--- diff --git a/1.10/networking/mesos-dns/expose-mesos-zone.md b/1.10/networking/service-discovery/mesos-dns/expose-mesos-zone.md similarity index 100% rename from 1.10/networking/mesos-dns/expose-mesos-zone.md rename to 1.10/networking/service-discovery/mesos-dns/expose-mesos-zone.md diff --git a/1.10/networking/mesos-dns/index.md b/1.10/networking/service-discovery/mesos-dns/index.md similarity index 100% rename from 1.10/networking/mesos-dns/index.md rename to 1.10/networking/service-discovery/mesos-dns/index.md diff --git a/1.10/networking/mesos-dns/mesos-dns-api.md b/1.10/networking/service-discovery/mesos-dns/mesos-dns-api.md similarity index 100% rename from 1.10/networking/mesos-dns/mesos-dns-api.md rename to 1.10/networking/service-discovery/mesos-dns/mesos-dns-api.md diff --git a/1.10/networking/mesos-dns/service-naming.md b/1.10/networking/service-discovery/mesos-dns/service-naming.md similarity index 100% rename from 1.10/networking/mesos-dns/service-naming.md rename to 1.10/networking/service-discovery/mesos-dns/service-naming.md diff --git a/1.10/networking/mesos-dns/troubleshooting.md b/1.10/networking/service-discovery/mesos-dns/troubleshooting.md similarity index 100% rename from 1.10/networking/mesos-dns/troubleshooting.md rename to 1.10/networking/service-discovery/mesos-dns/troubleshooting.md diff --git a/1.10/networking/load-balancing-vips/virtual-ip-addresses.md b/1.10/networking/service-discovery/vips/index.md similarity index 98% rename from 1.10/networking/load-balancing-vips/virtual-ip-addresses.md rename to 1.10/networking/service-discovery/vips/index.md index 80343c7f4..d603cf311 100644 --- a/1.10/networking/load-balancing-vips/virtual-ip-addresses.md +++ b/1.10/networking/service-discovery/vips/index.md @@ -1,6 +1,6 @@ --- -post_title: Using Virtual IP Addresses -menu_order: 10 +post_title: Virtual IP Addresses +menu_order: 20 --- DC/OS can map traffic from a single Virtual IP (VIP) to multiple IP addresses and ports. DC/OS VIPs are **name-based**, which means clients connect with a service address instead of an IP address. diff --git a/1.10/networking/tls-ssl/index.md b/1.10/networking/tls-ssl/index.md index 833318916..f276f863e 100644 --- a/1.10/networking/tls-ssl/index.md +++ b/1.10/networking/tls-ssl/index.md @@ -1,6 +1,6 @@ --- post_title: Securing communication with TLS -menu_order: 06 +menu_order: 100 --- You can set up secure HTTPS communication using a custom server certificate with your DC/OS cluster by [setting up a proxy](/docs/1.10/networking/tls-ssl/haproxy-adminrouter/) between the Admin Router and user agent requests coming in from outside of the cluster. diff --git a/1.10/networking/virtual-networks/cnm.md b/1.10/networking/virtual-networks/cnm.md new file mode 100644 index 000000000..13d12fe7f --- /dev/null +++ b/1.10/networking/virtual-networks/cnm.md @@ -0,0 +1,4 @@ +--- +post_title: CNM Support +menu_order: 40 +--- diff --git a/1.10/networking/virtual-networks/dcos-overlay.md b/1.10/networking/virtual-networks/dcos-overlay.md new file mode 100644 index 000000000..e55a58e84 --- /dev/null +++ b/1.10/networking/virtual-networks/dcos-overlay.md @@ -0,0 +1,95 @@ +--- +post_title: DC/OS Overlay +menu_order: 50 +-- + +# DC/OS Overlay +DC/OS Overlay provides an IP per container for Mesos and Docker containers alike. DC/OS Overlay uses CNI (Container Network Interface) for the [Mesos +Containerizer](http://mesos.apache.org/documentation/latest/containerizers/#Mesos) and Docker libnetwork for the [Docker +Containerizer](http://mesos.apache.org/documentation/latest/containerizers/#Docker). + +DC/OS Overlay allows containers launched through the Mesos Containerizer or Docker Containerizer to co-exist on the same IP network, allocating each container its own +unique IP address. DC/OS Overlay offers the following advantages: + +* Both Mesos and Docker containers can communicate from within a single node and between nodes on a cluster. +* Services can run in isolation from other traffic coming from any other virtual network or host in the cluster. +* You don't have to worry about potentially overlapping ports in applications, or using workarounds to avoid overlapping (e.g. using nonstandard ports for services). +* You can generate any number of instances of a class of tasks and have them all listen on the same port so that clients don’t have to do port discovery. +* You can run applications that require intra-cluster connectivity, like Cassandra, HDFS, and Riak. +* You can create multiple virtual networks to isolate different portions of your organization, for instance, development, marketing, and production. + +**Note:** Isolation guarantees among subnets depend on your firewall policies. + +### Architecture + +Here is the DC/OS Overlay architecture: + +![Overview of the DC/OS Overlay architecture](/docs/1.10/img/overlay-networks.png) + +DC/OS Overlay does not require an external IP address management (IPAM) solution because IP allocation is handled via the Mesos Master replicated log. DC/OS Overlay does +not support external IPAMs. + +The components of the DC/OS Overlay interact in the following ways: + +- Both the Mesos master and the Mesos agents run DC/OS overlay modules that communicate directly. + +- The CNI isolator is used for the Mesos containerizer. [DNI](https://docs.docker.com/engine/userguide/networking/) is used for the Docker containerizer, shelling out to +the Docker daemon. + +- For intra-node IP discovery we use an overlay orchestrator called Virtual Network Service. This operator-facing system component is responsible for programming the +overlay backend using a library called [lashup](https://github.com/dcos/lashup) that implements a gossip protocol to disseminate and coordinate overlay routing +information among all Mesos agents in the DC/OS cluster. + +**Note:** Your network must adhere to the [DC/OS system requirements](/docs/1.10/installing/custom/system-requirements/) to use DC/OS Overlay. + +### Limitations + +* DC/OS Overlay does not allow services to reserve IP addresses that result in ephemeral addresses for containers across multiple incarnations on the virtual network. +This restriction ensures that a given client connects to the correct service. + + [VIPs (virtual IP addresses)](/docs/1.10/networking/load-balancing-vips/) are built in to DC/OS and offer a clean way of allocating static addresses to services. If +you are using DC/OS Overlay, you should use VIPs to access your services to support cached DNS requests and static IP addresses. + +* The limitation on the total number of containers on DC/OS Overlay is the same value as the number of IP addresses available on the overlay subnet. However, the +limitation on the number of containers on an agent depends on the subnet (which will be a subset of the overlay subnet) allocated to the agent. For a given agent subnet, +half the address space is allocated to the `MesosContainerizer` and the other half is allocated to the `DockerContainerizer`. + +* In DC/OS overlay, the subnet of an virtual network is sliced into smaller subnets and these smaller subnets are allocated to agents. When an agent has exhausted its +allocated address range and a service tries to launch a container on the virtual network on this agent, the container launch will fail and the service will receive a +`TASK_FAILED` message. + + Since there is no API to report the exhaustion of addresses on an agent, it is up to the service to infer that containers cannot be launched on an virtual network due +to lack of IP addresses on the agent. This limitation has a direct impact on the behavior of services, such as Marathon, that try to launch services with a specified +number of instances. Due to this limitation, services such as Marathon might not be able to complete their obligation of launching a service on an virtual network if +they try to launch instances of a service on an agent that has exhausted its allocated IP address range. + + Keep this limitation in mind when debugging issues on frameworks that use an virtual network and you see the `TASK_FAILED` message. + +* DC/OS Overlay uses Linux bridge devices on agents to connect Mesos and Docker containers to the virtual network. The names of these bridge devices are derived from the +virtual network name. Since Linux has a limitation of fifteen characters on network device names, there is a character limit of thirteen characters for the virtual +network name (two characters are used to distinguish between a CNI bridge and a Docker bridge on the virtual network). + +* Certain names are reserved and cannot be used as DC/OS Overlay names. The is because DC/OS Overlay uses Docker networking underneath to connect Docker containers to +the overlay, which in turn reserves certain network names. The reserved names are: `host`, `bridge` and `default`. + +* [Marathon health checks](/docs/1.10/deploying-services/creating-services/health-checks/) will not work with certain DC/OS Overlay configurations. If you are not using +the default DC/OS Overlay configuration and Marathon is isolated from the virtual network, health checks will fail consistently even if the service is healthy. + + Marathon health checks _will_ work in any of the following circumstances: + + * You are using the default DC/OS Overlay configuration. + * Marathon has access to the virtual network. + * You use a [`command` health check](/docs/1.10/deploying-services/creating-services/health-checks/). + +# Virtual Network Service: DNS + +The [Virtual Network Service](/docs/1.10/overview/architecture/components/) maps names to IPs on your virtual network. You can use these DNS addresses to access your +task: + +* **Container IP:** Provides the container IP address: `..containerip.dcos.thisdcos.directory` +* **Auto IP:** Provides a best guess of a task's IP address: `..autoip.dcos.thisdcos.directory`. This is used during migrations to the overlay. + +Terminology: +* `taskname`: The name of the task +* `framework_name`: The name of the framework, if you are unsure, it is likely `marathon` + diff --git a/1.10/networking/virtual-networks/index.md b/1.10/networking/virtual-networks/index.md index 20b31a624..f31547295 100644 --- a/1.10/networking/virtual-networks/index.md +++ b/1.10/networking/virtual-networks/index.md @@ -5,73 +5,60 @@ feature_maturity: preview menu_order: 04 --- -DC/OS supports Container Networking Interface (CNI)-compatible virtual networking solutions, including [Calico](https://github.com/dcos/examples/tree/master/calico) and Contrail. DC/OS also provides a native virtual networking solution called DC/OS Overlay. +DC/OS supports Container Networking Interface (CNI)-compatible virtual networking solutions, including [Calico](https://github.com/dcos/examples/tree/master/calico) and Contrail. DC/OS also provides a native virtual networking solution called DC/OS Overlay. -# DC/OS Overlay -DC/OS Overlay provides an IP per container for Mesos and Docker containers alike. DC/OS Overlay uses CNI (Container Network Interface) for the [Mesos Containerizer](http://mesos.apache.org/documentation/latest/containerizers/#Mesos) and Docker libnetwork for the [Docker Containerizer](http://mesos.apache.org/documentation/latest/containerizers/#Docker). +# Virtual Networks on DC/OS -DC/OS Overlay allows containers launched through the Mesos Containerizer or Docker Containerizer to co-exist on the same IP network, allocating each container its own unique IP address. DC/OS Overlay offers the following advantages: +DC/OS enables virtual networking through the use of virtual networks. DC/OS virtual networks enable you to provide each container in the system with a unique IP address (“IP-per-container”) with isolation guarantees amongst subnets. DC/OS virtual networks offer the following advantages: * Both Mesos and Docker containers can communicate from within a single node and between nodes on a cluster. -* Services can run in isolation from other traffic coming from any other virtual network or host in the cluster. -* You don't have to worry about potentially overlapping ports in applications, or using workarounds to avoid overlapping (e.g. using nonstandard ports for services). +* Services can be created such that their traffic is isolated from other traffic coming from any other virtual network or host in the cluster. +* They remove the need to worry about potentially overlapping ports in applications, or the need to use nonstandard ports for services to avoid overlapping. * You can generate any number of instances of a class of tasks and have them all listen on the same port so that clients don’t have to do port discovery. * You can run applications that require intra-cluster connectivity, like Cassandra, HDFS, and Riak. * You can create multiple virtual networks to isolate different portions of your organization, for instance, development, marketing, and production. -**Note:** Isolation guarantees among subnets depend on your firewall policies. - -### Architecture - -Here is the DC/OS Overlay architecture: - -![Overview of the DC/OS Overlay architecture](/docs/1.10/img/overlay-networks.png) - -DC/OS Overlay does not require an external IP address management (IPAM) solution because IP allocation is handled via the Mesos Master replicated log. DC/OS Overlay does not support external IPAMs. - -The components of the DC/OS Overlay interact in the following ways: - -- Both the Mesos master and the Mesos agents run DC/OS overlay modules that communicate directly. - -- The CNI isolator is used for the Mesos containerizer. [DNI](https://docs.docker.com/engine/userguide/networking/) is used for the Docker containerizer, shelling out to the Docker daemon. - -- For intra-node IP discovery we use an overlay orchestrator called Virtual Network Service. This operator-facing system component is responsible for programming the overlay backend using a library called [lashup](https://github.com/dcos/lashup) that implements a gossip protocol to disseminate and coordinate overlay routing information among all Mesos agents in the DC/OS cluster. - -**Note:** Your network must adhere to the [DC/OS system requirements](/docs/1.10/installing/custom/system-requirements/) to use DC/OS Overlay. - -### Limitations - -* DC/OS Overlay does not allow services to reserve IP addresses that result in ephemeral addresses for containers across multiple incarnations on the virtual network. This restriction ensures that a given client connects to the correct service. - - [VIPs (virtual IP addresses)](/docs/1.10/networking/load-balancing-vips/) are built in to DC/OS and offer a clean way of allocating static addresses to services. If you are using DC/OS Overlay, you should use VIPs to access your services to support cached DNS requests and static IP addresses. - -* The limitation on the total number of containers on DC/OS Overlay is the same value as the number of IP addresses available on the overlay subnet. However, the limitation on the number of containers on an agent depends on the subnet (which will be a subset of the overlay subnet) allocated to the agent. For a given agent subnet, half the address space is allocated to the `MesosContainerizer` and the other half is allocated to the `DockerContainerizer`. - -* In DC/OS overlay, the subnet of an virtual network is sliced into smaller subnets and these smaller subnets are allocated to agents. When an agent has exhausted its allocated address range and a service tries to launch a container on the virtual network on this agent, the container launch will fail and the service will receive a `TASK_FAILED` message. - - Since there is no API to report the exhaustion of addresses on an agent, it is up to the service to infer that containers cannot be launched on an virtual network due to lack of IP addresses on the agent. This limitation has a direct impact on the behavior of services, such as Marathon, that try to launch services with a specified number of instances. Due to this limitation, services such as Marathon might not be able to complete their obligation of launching a service on an virtual network if they try to launch instances of a service on an agent that has exhausted its allocated IP address range. - - Keep this limitation in mind when debugging issues on frameworks that use an virtual network and you see the `TASK_FAILED` message. - -* DC/OS Overlay uses Linux bridge devices on agents to connect Mesos and Docker containers to the virtual network. The names of these bridge devices are derived from the virtual network name. Since Linux has a limitation of fifteen characters on network device names, there is a character limit of thirteen characters for the virtual network name (two characters are used to distinguish between a CNI bridge and a Docker bridge on the virtual network). - -* Certain names are reserved and cannot be used as DC/OS Overlay names. The is because DC/OS Overlay uses Docker networking underneath to connect Docker containers to the overlay, which in turn reserves certain network names. The reserved names are: `host`, `bridge` and `default`. - -* [Marathon health checks](/docs/1.10/deploying-services/creating-services/health-checks/) will not work with certain DC/OS Overlay configurations. If you are not using the default DC/OS Overlay configuration and Marathon is isolated from the virtual network, health checks will fail consistently even if the service is healthy. - - Marathon health checks _will_ work in any of the following circumstances: - - * You are using the default DC/OS Overlay configuration. - * Marathon has access to the virtual network. - * You use a [`command` health check](/docs/1.10/deploying-services/creating-services/health-checks/). - -# Virtual Network Service: DNS - -The [Virtual Network Service](/docs/1.10/overview/architecture/components/) maps names to IPs on your virtual network. You can use these DNS addresses to access your task: - -* **Container IP:** Provides the container IP address: `..containerip.dcos.thisdcos.directory` -* **Auto IP:** Provides a best guess of a task's IP address: `..autoip.dcos.thisdcos.directory`. This is used during migrations to the overlay. - -Terminology: -* `taskname`: The name of the task -* `framework_name`: The name of the framework, if you are unsure, it is likely `marathon` +**Note:** Isolation guarantees among subnets depend on your CNI implementation and/or your firewall policies. + +# Using Virtual Networks + +First, you or the data center operator needs to [configure the virtual networks](/docs/1.10/networking/virtual-networks/). + +Virtual networks are configured at install time. You or the data center operator will specify a canonical name for each network in the `config.yaml`. When your service needs to launch a container, refer to it by that canonical name. + +To use an virtual network in a Marathon app definition, specify the `"network": "USER"` property along with an `ipAddress` field in the form: `{"ipAddress": {"network": "$MYNETWORK"}}`. The value of `$MYNETWORK` is the canonical name of the network. + +# Example + +The following Marathon application definition specifies a network named `dcos-1`, which refers to the target DC/OS virtual network of the same name. + +```json +{ + "id":"my-networking", + "cmd":"env; ip -o addr; sleep 30", + "cpus":0.10, + "mem":64, + "instances":1, + "backoffFactor":1.14472988585, + "backoffSeconds":5, + "ipAddress":{ + "networkName":"dcos-1" + }, + "container":{ + "type":"DOCKER", + "docker":{ + "network":"USER", + "image":"busybox", + "portMappings":[ + { + "containerPort":123, + "servicePort":80, + "name":"foo" + } + ] + } + } +} +``` + +Learn more about ports and networking in [Marathon](/docs/1.10/deploying-services/service-ports/).