docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

D4ic docs updates (#5754) 

* Revising service load balancer docs
This commit is contained in:
Art 2018-01-16 15:01:35 -05:00 committed by Misty Stanley-Jones
parent 4d2e963b4e
commit 8058da6e0a
8 changed files with 155 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
_data/toc.yaml
View File

@ -101,6 +101,8 @@ guides:
title: FAQs
- path: /docker-for-ibm-cloud/opensource/
title: Open source licensing
- path: /docker-for-ibm-cloud/release-notes/
title: Release notes
- sectiontitle: Docker for AWS
section:
- path: /docker-for-aws/why/
@ -509,7 +511,7 @@ guides:
title: Kubernetes Benchmark
- path: /compliance/fedramp/
title: FedRAMP
- sectiontitle: Open source at Docker
section:
- path: /opensource/

8
docker-for-ibm-cloud/administering-swarms.md
View File

@ -46,14 +46,14 @@ To create a Docker EE for IBM Cloud cluster from the CLI:
| `--sl-api-key`, `-k` | [Log in to IBM Cloud infrastructure](https://control.softlayer.com/), select your profile, and locate your **Authentication Key** under the API Access Information section. | | Required |
| `--ssh-label`, `--label` | Your IBM Cloud infrastructure SSH key label for the manager node. To create a key, [log in to IBM Cloud infrastructure](https://control.softlayer.com/) and select **Devices > Manage > SSH Keys > Add**. Copy the key label and insert it here. | | Required |
| `--ssh-key` | The path to the SSH key on your local client that matches the SSH key label in your IBM Cloud infrastructure account. | | Required |
| `--swarm-name`, `--name` | The name for your swarm and prefix for the names of each node. | d4ic | Required |
| `--docker-ee-url` | The Docker EE installation URL associated with your subscription. For beta, you received this in your welcome email. | | Required |
| `--swarm-name`, `--name` | The name for your swarm and prefix for the names of each node. | | Required |
| `--docker-ee-url` | The Docker EE installation URL associated with your subscription. [Email IBM](mailto:sealbou@us.ibm.com) to get a trial subscription during the beta. | | Required |
| `--manager` | Deploy 1, 3, or 5 manager nodes. | 3 | Optional |
| `--workers`, `-w` | Deploy a minimum of 1 and maximum of 10 worker nodes. | 3 | Optional |
| `--datacenter`, `-d` | The location (data center) that you deploy the cluster to. Availabe locations are dal12, dal13, fra02, hkg02, lon04, par01, syd01, syd04, tor01, wdc06, wdc07. | wdc07 | Optional |
| `--verbose`, `-v` | Enable verbose mode | | Optional |
| `--hardware` | If "dedicated" then the nodes are created on hosts with compute instances in the same account. | Shared | Optional |
| `--manager-machine-type` | The machine type of the manager nodes: u1c.1x2, u1c.2x4, b1c.4x16, b1c.16x64, b1c.32x128, or b1c.56x242. More powerful machine types cost more, but deliver better performance. For example, u1c.2x4 is 2 cores and 4 GB memory, and b1c.56x242 is 56 cores and 242 GB memory. | u1c.2x4 | Optional |
| `--manager-machine-type` | The machine type of the manager nodes: u1c.1x2, u1c.2x4, b1c.4x16, b1c.16x64, b1c.32x128, or b1c.56x242. More powerful machine types cost more, but deliver better performance. For example, u1c.2x4 is 2 cores and 4 GB memory, and b1c.56x242 is 56 cores and 242 GB memory. | b1c.4x16 | Optional |
| `--worker-machine-type` | The machine type of the worker nodes: u1c.1x2, u1c.2x4, b1c.4x16, b1c.16x64, b1c.32x128, or b1c.56x242. More powerful machine types cost more, but deliver better performance. For example, u1c.2x4 is 2 cores and 4 GB memory, and b1c.56x242 is 56 cores and 242 GB memory. | u1c.1x2 | Optional |
4. Create the cluster. Use the `--swarm-name` flag to name your cluster, and fill in the credentials, SSH, and Docker EE installation URL variables with the information that you retrieved before you began.
@ -166,7 +166,7 @@ Before you begin, [create a cluster](#create-swarms). Note the its **Name** and
...
```
2. Retrieve the load balancer IP address.
2. Retrieve the **UCP URL** address.
```bash
$ bx d4ic list --sl-user user.name.1234567 --sl-api-key api_key

6
docker-for-ibm-cloud/cli-ref.md
View File

@ -37,14 +37,14 @@ $ bx d4ic create --sl-user SOFTLAYER_USERNAME --sl-api-key SOFTLAYER_API_KEY --s
| `--sl-api-key`, `-k` | [Log in to IBM Cloud infrastructure](https://control.softlayer.com/), select your profile, and locate your **Authentication Key** under the API Access Information section. | | Required |
| `--ssh-label`, `--label` | Your IBM Cloud infrastructure SSH key label for the manager node. To create a key, [log in to IBM Cloud infrastructure](https://control.softlayer.com/) and select **Devices > Manage > SSH Keys > Add**. Copy the key label and insert it here. | | Required |
| `--ssh-key` | The path to the SSH key on your local client that matches the SSH key label in your IBM Cloud infrastructure account. | | Required |
| `--swarm-name`, `--name` | The name for your swarm and prefix for the names of each node. | d4ic | Required |
| `--docker-ee-url` | The Docker EE installation URL associated with your subscription. For beta, you received this in your welcome email. | | Required |
| `--swarm-name`, `--name` | The name for your swarm and prefix for the names of each node. | | Required |
| `--docker-ee-url` | The Docker EE installation URL associated with your subscription. [Email IBM](mailto:sealbou@us.ibm.com) to get a trial subscription during the beta. | | Required |
| `--manager` | Deploy 1, 3, or 5 manager nodes. | 3 | Optional |
| `--workers`, `-w` | Deploy a minimum of 1 and maximum of 10 worker nodes. | 3 | Optional |
| `--datacenter`, `-d` | The location (data center) that you deploy the cluster to. Availabe locations are dal12, dal13, fra02, hkg02, lon04, par01, syd01, syd04, tor01, wdc06, wdc07. | wdc07 | Optional |
| `--verbose`, `-v` | Enable verbose mode | | Optional |
| `--hardware` | If "dedicated" then the nodes are created on hosts with compute instances in the same account. | Shared | Optional |
| `--manager-machine-type` | The machine type of the manager nodes: u1c.1x2, u1c.2x4, b1c.4x16, b1c.16x64, b1c.32x128, or b1c.56x242. Higher machine types cost more, but deliver better performance: for example, u1c.2x4 is 2 cores and 4 GB memory, and b1c.56x242 is 56 cores and 242 GB memory. | u1c.2x4 | Optional |
| `--manager-machine-type` | The machine type of the manager nodes: u1c.1x2, u1c.2x4, b1c.4x16, b1c.16x64, b1c.32x128, or b1c.56x242. Higher machine types cost more, but deliver better performance: for example, u1c.2x4 is 2 cores and 4 GB memory, and b1c.56x242 is 56 cores and 242 GB memory. | b1c.4x16 | Optional |
| `--worker-machine-type` | The machine type of the worker nodes: u1c.1x2, u1c.2x4, b1c.4x16, b1c.16x64, b1c.32x128, or b1c.56x242. Higher machine types cost more, but deliver better performance: for example, u1c.2x4 is 2 cores and 4 GB memory, and b1c.56x242 is 56 cores and 242 GB memory. | u1c.1x2 | Optional |
| `--version` | The Docker EE version of the created cluster. For the beta, only the default version is available. | Default version | Optional |

11
docker-for-ibm-cloud/faqs.md
View File

@ -7,7 +7,7 @@ title: Docker for IBM Cloud frequently asked questions (FAQs)
## How do I sign up?
Docker EE for IBM Cloud is an unmanaged, native Docker environment within IBM Cloud that runs Docker Enterprise Edition software. Docker EE for IBM Cloud is available on **December 20th 2017 as a closed Beta**.
[Request access to the beta here](https://www.ibm.com/us-en/marketplace/docker-for-ibm-cloud). Once you do, we'll be in touch shortly!
[Request access to the beta](mailto:sealbou@us.ibm.com). Once you do, we'll be in touch shortly!
## What IBM Cloud infrastructure permissions do I need?
@ -60,6 +60,7 @@ Docker EE for IBM Cloud is an unmanaged, native Docker environment within IBM Cl
<li>View bandwidth statistics</li>
<li>Add IP addresses</li>
<li>Manage email delivery service</li>
<li>*Manage Network VLAN Spanning</li>
</ul></td>
</tr>
<tr>
@ -123,6 +124,10 @@ The Docker EE for IBM Cloud CLI plug-in simplifies your interaction with IBM Clo
Instead of including these in each command, you can [set your environment variables](/docker-for-ibm-cloud/index.md#set-infrastructure-environment-variables).
## Why can't I target an organization or space in IBM Cloud?
Before you can target an organization or space in IBM Cloud, the account owner or administrator must set up the organization or space. See [Creating organizations and spaces](https://console.bluemix.net/docs/admin/orgs_spaces.html#orgsspacesusers) for more information.
## Can I manually change the load balancer configuration?
No. If you make any manual changes to the load balancer, they are removed the next time that the load balancer is updated or swarm changes are made. This is because the swarm service configuration is the source of record for service ports. If you add listeners to the load balancer manually, they could conflict with what is in cluster, and cause issues.
@ -137,6 +142,10 @@ SSH into a manager node. Manager nodes are accessed on port 56422.
alias ssh-docker='function __t() { ssh-keygen -R [$1]:56422 > /dev/null 2>&1; ssh -A -p 56422 -o StrictHostKeyChecking=no docker@$1; unset -f __t; }; __t'
```
## Are there any known issues?
Yes. News, updates, and known issues are recorded by version on the [Release notes](release-notes.md) page.
## Where do I report problems or bugs?
Contact us through email at docker-for-ibmcloud-beta@docker.com.

4
docker-for-ibm-cloud/index.md
View File

@ -9,7 +9,7 @@ redirect_from:
Docker EE for IBM Cloud is an unmanaged, native Docker environment within IBM Cloud that runs Docker Enterprise Edition software. Docker EE for IBM Cloud is available on **December 20th 2017 as a closed Beta**.
[Request access to the closed beta here](https://www.ibm.com/us-en/marketplace/docker-for-ibm-cloud). In the welcome email you receive, you are given the Docker EE installation URL that you use for the beta.
[Email IBM to request access to the closed beta](mailto:sealbou@us.ibm.com). In the welcome email you receive, you are given the Docker EE installation URL that you use for the beta.
## Prerequisites
@ -38,7 +38,7 @@ Log in to [IBM Cloud infrastructure](https://control.softlayer.com/), select you
### Environment
If you have not already, [create a space](https://console.bluemix.net/docs/admin/orgs_spaces.html#spaceinfo) in IBM Cloud.
If you have not already, [create an organization and space](https://console.bluemix.net/docs/admin/orgs_spaces.html#orgsspacesusers) in IBM Cloud. You must be the account owner or administrator to complete this step.
## Install the CLIs

142
docker-for-ibm-cloud/load-balancer.md
View File

@ -62,7 +62,17 @@ Use the load balancer to access [DTR](/datacenter/dtr/2.4/guides/).
**Tip**: Your user name is `admin` or the user name that your admin created for you. You got the password when you [created the cluster](administering-swarms.md#create-swarms) or when your admin created your credentials.
## Service load balancer
When you create a service, any ports that are opened with `-p` are automatically exposed through the load balancer. For example:
When you create a service, any ports that are opened with `--publish` or `-p` are automatically published through the load balancer.
> Reserved ports
>
> Several ports are reserved and cannot be used to expose services:
> * 56501 for the service load balancer management.
> * 443 for the UCP web UI.
> * 56443 for the Agent.
For example:
```bash
$ docker service create --name nginx -p 80:80 nginx
@ -74,9 +84,13 @@ on that port to your service.
> Note: 10 ports on the service load balancer
>
> Each cluster's service load balancer can have 10 ports opened. If you create new services or update a service to publish it on a port but already used 10 ports, new ports are not added and the service cannot be accessed through the load balancer.
> If you need more than 10 ports, you can explore alternative solutions such as [UCP domain names](https://docs.docker.com/datacenter/ucp/2.2/guides/admin/configure/use-domain-names-to-access-services/) or [Træfik](https://github.com/containous/traefik). You can also [create another cluster](administering-swarms.md#create-swarms).
> If you need more than 10 ports, you can explore alternative solutions such as [UCP domain names](/datacenter/ucp/2.2/guides/admin/configure/use-domain-names-to-access-services/) or [Træfik](https://github.com/containous/traefik). You can also [create another cluster](administering-swarms.md#create-swarms).
### Accessing a service with the service load balancer
To learn more about general swarm networking, see the [Docker container networking](/engine/userguide/networking/) and [Manage swarm service networks](/engine/swarm/networking/) guides.
### Access a service with the service load balancer
Get a publicly accessible HTTP URL for your app by publishing a Docker service on an unused port. For secure HTTPS URLs, see [Services with SSL certificates](#services-with-ssl-certificates).
1. Connect to your Docker EE for IBM Cloud swarm. Navigate to the directory where you [downloaded the UCP credentials](administering-swarms.md#download-client-certificates) and run the script. For example:
@ -84,34 +98,78 @@ on that port to your service.
$ cd filepath/to/certificate/repo && source env.sh
```
2. Create the service specifying the port on which you want the service exposed. For example:
2. Create the service that you want to expose by using the `docker service create` [command](/engine/reference/commandline/service_create/). For example:
```bash
$ docker service create --name go-demo \
-e DB=go-demo-db \
--network go-demo \
--publish 8080:8080 \
vfarcic/go-demo
$ docker service create --name nginx-test \
--publish 8080:80 \
--replicas 3 \
nginx
```
3. Get the name of the cluster, and then use it to get the service load balancer URL:
3. List the name of the cluster such as `mycluster`, and then use it to show the service (**svc**) load balancer URL:
```bash
$ bx d4ic list --sl-user user.name.1234567 --sl-api-key api_key
$ bx d4ic show --swarm-name my_swarm --sl-user user.name.1234567 --sl-api-key api_key
$ bx d4ic show --swarm-name mycluster --sl-user user.name.1234567 --sl-api-key api_key
```
4. To access a service that you have previously exposed on a port, use the `service-lb-url` that you retrieved. For example:
4. To access the service that you exposed on a port, use the service (**svc**) load balancer URL that you retrieved. The load balancer might need a few minutes to update. For example:
```bash
$ curl https://service-lb-url:8080/demo/hello
$ curl mycluster-svc-1234567-wdc07.lb.bluemix.net:8080/
...
<title>Welcome to nginx!</title>
...
```
### Services with SSL certificates
Use [IBM Cloud infrastructure SSL Certificates](https://knowledgelayer.softlayer.com/topic/ssl-certificates) to authenticate and encrypt online transactions that are transmitted through your cluster's load balancer.
You can publicly expose your app securely with an HTTPS URL. Use [IBM Cloud infrastructure SSL Certificates](https://knowledgelayer.softlayer.com/topic/ssl-certificates) to authenticate and encrypt online transactions that are transmitted through your cluster's load balancer.
When you create a certificate for your domain, specify the **Common Name**. When you create the Docker service, include the certificate common name to use the certificate for SSL termination for your service.
Learn more about the [labels for SSL termination and health check paths](#labels-for-ssl-termination-and-health-check-paths), then follow along with an [example command to expose a service on HTTPS](#example-command-for-https).
#### Labels for SSL termination and health check paths
When you create the Docker service to expose your app with an HTTPS URL, you need to specify two labels that:
* Specify your SSL certificate's **Common Name**.
* Set the health check path.
**Start a service that uses SSL termination**:
Start a service that listens on ports that you specify. The service load balancer provides SSL termination on ports that use your SSL certificate's common name, `com.ibm.d4ic.lb.cert=certificate-common-name`, when you create the service.
In the label, you must append `@HTTPS:port` to list the ports that you want to publish.
For example:
```bash
$ docker service create --name name \
...
--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:444
...
```
To specify other or multiple ports, append them as follows:
* Links HTTPS to port 444: `--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:444`
* Links HTTPS to ports 444 and 8080: `--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:444,HTTPS:8080`
**Set a health check path when using SSL termination**:
By default, the service load balancer sets a health check path to `/`. If the service cannot respond with a 200 message to a `GET` request on the `/` path, then you must include a health monitor path label when you create the service. For example:
```bash
--label com.ibm.d4ic.healthcheck.path=/demo/hello@444
```
When the route is published, the health check is set to the path that you specify in the label. Choose a path that can respond with a 200 message to a `GET` request.
#### Example command for HTTPS
The following `docker service create` command expands on the example from the [previous section](#access-a-service-with-the-service-load-balancer) to create a demo service that is published on a different port than the default and includes a health check path.
Before you begin:
1. Log in to [IBM Cloud infrastructure](https://control.softlayer.com/).
@ -120,41 +178,37 @@ Before you begin:
3. Note the certificate **Common Name**.
**Start a service that uses SSL termination**: Start a service that listens on ports `80` and `443`. The service load balancer provides SSL termination on port `443` that uses your SSL certificate's common name, `com.ibm.d4ic.lb.cert=certificate-common-name`, when you create the service.
Steps:
In the label, append `@HTTPS:port` to list the ports you want to expose.
1. Connect to your Docker EE for IBM Cloud swarm. Navigate to the directory where you [downloaded the UCP credentials](administering-swarms.md#download_client_certificates) and run the script. For example:
For example:
```bash
$ cd filepath/to/certificate/repo && source env.
```
```bash
$ docker service create --name name \
...
--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:443
...
```
2. Create the service that you want to expose by using the `docker service create` [command](/engine/reference/commandline/service_create/). For example:
To specify other or multiple ports, append them as follows:
```bash
$ docker service create --name nginx-test \
--publish 444:80 \
--replicas 3 \
--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:444 \
--label com.ibm.d4ic.healthcheck.path=/@444 \
nginx
```
* Links HTTPS to port 444: `--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:444`
* Links HTTPS to ports 444 and 8080: `--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:444,HTTPS:8080`
3. List the name of the cluster such as `mycluster`, and then use it to show the service (**svc**) load balancer URL:
**Set a health check path**: By default, the service load balancer sets a health check path to `/`. If the service cannot respond with a 200 message to a `GET` request on the `/` path, then include a health monitor path label when you create the service. For example:
```bash
$ bx d4ic list --sl-user user.name.1234567 --sl-api-key api_key
$ bx d4ic show --swarm-name mycluster --sl-user user.name.1234567 --sl-api-key api_key
```
```bash
--label com.ibm.d4ic.healthcheck.path=/demo/hello@443
```
4. To access the service that you exposed on a port, use the service (**svc**) load balancer URL that you retrieved. The load balancer might need a few minutes to update. For example:
When the route is published, the health check is set to the path that you specify in the label. Choose a path that can respond with a 200 message to a `GET` request.
**Example command**: The following `docker service create` command expands on the example from the [previous section](#access-a-service-with-the-service-load-balancer) to create a demo service that is exposed on a different port than the default and includes a health check path. It is based on the `vfarcic/go-demo` image.
```bash
$ docker service create --name go-demo \
-e DB=go-demo-db \
--network go-demo \
--publish 8080:8080 \
--replicas 3 \
--label com.ibm.d4ic.lb.cert=certificate-common-name@HTTPS:8080 \
--label com.ibm.d4ic.healthcheck.path=/demo/hello@8080 \
vfarcic/go-demo
```
```bash
$ curl --cacert https://mycluster-svc-1234567-wdc07.lb.bluemix.net:444
...
<title>Welcome to nginx!</title>
...
```

8
docker-for-ibm-cloud/quickstart.md
View File

@ -8,7 +8,7 @@ title: Docker EE for IBM Cloud (Beta) Quick Start
Are you ready to orchestrate Docker Enterprise Edition swarm clusters that are enhanced with the full suite of secure IBM Cloud platform, infrastructure, and Watson services? Great! Let's get you started.
To request access to the closed beta, [contact us](https://www.ibm.com/us-en/marketplace/docker-for-ibm-cloud).
To request access to the closed beta, [email IBM](mailto:sealbou@us.ibm.com).
![Getting started with Docker for IBM Cloud in 4 easy steps](img/quickstart.png)
@ -24,9 +24,9 @@ To request access to the closed beta, [contact us](https://www.ibm.com/us-en/mar
* [Add your SSH key to IBM Cloud infrastructure](https://knowledgelayer.softlayer.com/procedure/add-ssh-key), label it, and note the label.
* Log in to [IBM Cloud infrastructure](https://control.softlayer.com/), select your user profile, and under the **API Access Information** section retrieve your **API Username** and **Authentication Key**.
3. If you have not already, [create a space](https://console.bluemix.net/docs/admin/orgs_spaces.html#spaceinfo) to use when using IBM Cloud services.
3. If you have not already, [create an organization and space](https://console.bluemix.net/docs/admin/orgs_spaces.html#orgsspacesusers) to use when using IBM Cloud services. You must be the account owner or administrator to complete this step.
4. Get the Docker EE URL associated with your subscription. For beta, you received this in your welcome email.
4. Get the Docker EE URL associated with your subscription. [Email IBM](mailto:sealbou@us.ibm.com) to get a trial subscription during the beta.
5. Set your environment variables to use your IBM Cloud infrastructure credentials and your Docker EE installation URL. For example:
@ -113,7 +113,7 @@ Check it out: Docker for IBM Cloud uses [Docker Universal Control Plane (UCP)](/
...
```
2. Retrieve your cluster's load balancer URL:
2. Retrieve your cluster's **UCP URL**:
```bash
$ bx d4ic list --sl-user user.name.1234567 --sl-api-key api_key

31
docker-for-ibm-cloud/release-notes.md Normal file
View File

@ -0,0 +1,31 @@
---
description: Release notes for Docker EE for IBM Cloud. Learn more about the changes introduced in the latest versions.
keywords: ibm cloud, ibm, iaas, release notes
title: Docker EE for IBM Cloud (beta) release notes
---
Here you can learn about new features, bug fixes, breaking changes, and known issues for the latest Docker EE for IBM Cloud (beta) version.
## Version 1.0.1 (closed beta)
(20 December 2017)
Docker Enterprise Edition for IBM Cloud is a Container-as-a-Service platform that helps you modernize and extend your applications. It provides an unmanaged, native Docker environment running within IBM Cloud, giving you the ability to enhance your apps with services from the IBM Cloud catalog such as Watson, Internet of Things, Data, Logging, Monitoring, and many more.
The beta is based on the latest Docker EE version 17.06. You receive a 90-day Docker EE license for 20 Linux x86-64 nodes that you use when creating a cluster with the IBM Cloud `bx d4ic` CLI plug-in.
[Sign up for the closed beta](mailto:sealbou@us.ibm.com). Then use the [quick start](quickstart.md) to spin up your first Docker EE for IBM Cloud swarm.
### Known issues
#### Service load balancer has the configuration of an older service
**What it is**: You update (`docker service update`) or a create a new service after removing an old one (`docker service rm` then immediately `docker service create`) with a change to [the certificate or health check path](load-balancer.md#labels-for-ssl-termination-and-health-check-paths) values. The service load balancer still has the configuration of the older service.
**Why it's happening**: The InfraKit ingress controller does not check if the certificate or health check path has changed between the service load balancer configuration and the Docker swarm listener configuration. This results in the old configuration not getting updated to the new values.
**What to do about it**: Avoid updating a service with the `docker service update` command.
First remove the old service with `docker service rm`, and then wait for a time so that the service load balancer configuration updates. Then, create the new service with `docker service create`.
If you must use `docker service update`, remove the configuration for the port of the service load balancer in the [IBM Cloud infrastructure web UI](https://control.softlayer.com/). The InfraKit ingress controller then recreates the configuration with the new values.