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

Rewritten Custom CNI to become Unmanaged CNI in UCP Docs (#8799) 

* Rewritten Custom CNI to become Unmanaged CNI

Here I have rewritten the Unmanaged CNI page with Docker UCP. The
changes are:

- Clarifying the support position
- Providing clear instructions on how to bring up UCP and then install a
custom CNI plugin
- Removes unneccesary items like disabling IPIP which is not related to
this page.

Signed-off-by: Olly Pomeroy <olly@docker.com>

* Updated following Uday's feedback

* Add editorial review
This commit is contained in:
Olly P 2019-05-28 21:55:25 +01:00 committed by Maria Bermudez
parent 995244c5e0
commit 1456d52923
3 changed files with 100 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_data/toc.yaml
View File

@ -1371,7 +1371,7 @@ manuals:
path: /ee/ucp/kubernetes/layer-7-routing/ path: /ee/ucp/kubernetes/layer-7-routing/
- title: Create a service account for a Kubernetes app - title: Create a service account for a Kubernetes app
path: /ee/ucp/kubernetes/create-service-account/ path: /ee/ucp/kubernetes/create-service-account/
- title: Install a CNI plugin - title: Install an unmanaged CNI plugin
path: /ee/ucp/kubernetes/install-cni-plugin/ path: /ee/ucp/kubernetes/install-cni-plugin/
- title: Kubernetes network encryption - title: Kubernetes network encryption
path: /ee/ucp/kubernetes/kubernetes-network-encryption/ path: /ee/ucp/kubernetes/kubernetes-network-encryption/

10
ee/ucp/admin/install/index.md
View File

@ -75,12 +75,12 @@ To install UCP:
To find what other options are available in the install command, check the To find what other options are available in the install command, check the
[reference documentation](/reference/ucp/3.1/cli/install.md). [reference documentation](/reference/ucp/3.1/cli/install.md).
> Custom CNI plugins > Custom Container Networking Interface (CNI) plugins
> >
> If you want to use a third-party Container Networking Interface (CNI) plugin, > UCP will install [Project Calico](https://docs.projectcalico.org/v3.7/introduction/)
> like Flannel or Weave, modify the previous command line to include the > for container-to-container communication for Kubernetes. A platform operator may
> `--cni-installer-url` option. Learn how to > choose to install an alternative CNI plugin, such as Weave or Flannel. Please see
> [install a CNI plugin](../../kubernetes/install-cni-plugin.md). >[Install an unmanaged CNI plugin](/ee/ucp/kubernetes/install-cni-plugin/).
{: important} {: important}
## Step 5: License your installation ## Step 5: License your installation

167
ee/ucp/kubernetes/install-cni-plugin.md
View File

@ -1,98 +1,119 @@
--- ---
title: Install a CNI plugin title: Install an unmanaged CNI plugin
description: Learn how to install a Container Networking Interface plugin on Docker Universal Control Plane. description: Learn how to install a Container Networking Interface (CNI) plugin on Docker Universal Control Plane.
keywords: ucp, cli, administration, kubectl, Kubernetes, cni, Container Networking Interface, flannel, weave, ipip, calico keywords: ucp, kubernetes, cni, container networking interface, flannel, weave, calico
--- ---
For Docker Universal Control Plane, [Project Calico](https://docs.projectcalico.org/v3.0/introduction/) For Docker Universal Control Plane (UCP), [Calico](https://docs.projectcalico.org/v3.7/introduction/)
provides the secure networking functionality for the container communication with Kubernetes. provides the secure networking functionality for container-to-container communication within
Kubernetes. UCP handles the lifecycle of Calico and packages it with UCP
installation and upgrade. Additionally, the Calico deployment included with
UCP is fully supported with Docker providing guidance on the [CNI components]
(https://github.com/projectcalico/cni-plugin).
Docker EE supports Calico and installs the At install time, UCP can be configured to install an alternative CNI plugin
built-in [Calico](https://github.com/projectcalico/cni-plugin) plugin, but you can override that and to support alternative use cases. The alternative CNI plugin is certified by
install a Docker certified plugin. Docker and its partners, and published on Docker Hub. UCP components are still
fully supported by Docker and respective partners. Docker will provide
pointers to basic configuration, however for additional guidance on managing third party
CNI components, the platform operator will need to refer to the partner documentation
or contact that third party.
> **Note**: The `--cni-installer-url` option is deprecated as of UCP 3.1. It is replaced by the `--unmanaged-cni` option. ## Install an unmanaged CNI Plugin on Docker UCP
# Install UCP with a custom CNI plugin Once a platform operator has complied with [UCP system
requirements](/ee/ucp/admin/install/system-requirements/) and
taken into consideration any requirements for the custom CNI plugin, you can
[run the UCP install command with the `--unmanaged-cni` flag](/ee/ucp/kubernetes/install-cni-plugin/)
to bring up the platform.
Modify the [UCP install command-line](../admin/install/index.md#step-4-install-ucp) This command will install UCP, and bring up components
to add the `--cni-installer-url` [option](/reference/ucp/3.0/cli/install.md), like the user interface and the RBAC engine. UCP components that
providing a URL for the location of the CNI plugin's YAML file: require Kubernetes Networking, such as Metrics, will not start and will stay in
a `Container Creating` state in Kubernetes, until a CNI is installed.
### Install UCP without a CNI Plugin
Once connected to a manager node with the Docker Enterprise Engine installed,
you are ready to install UCP with the `--unmanaged-cni` flag.
```bash ```bash
docker container run --rm -it --name ucp \ docker container run --rm -it --name ucp \
-v /var/run/docker.sock:/var/run/docker.sock \ -v /var/run/docker.sock:/var/run/docker.sock \
{{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} install \ {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} install \
--host-address <node-ip-address> \ --host-address <node-ip-address> \
--unmanaged-cni <true|false> \ --unmanaged-cni \
--interactive --interactive
``` ```
> **Note**: Setting `--unmanaged-cni` to `true` value installs UCP without a managed CNI plugin. UCP and the Once the installation is complete, you will be able to access UCP in the browser.
> Kubernetes components will be running but pod-to-pod networking will not function until a CNI plugin is manually Note that the manager node will be unhealthy as the kubelet will
> installed. This will impact some functionality of UCP until a CNI plugin is running. report `NetworkPluginNotReady`. Additionally, the metrics in the UCP dashboard
will also be unavailable, as this runs in a Kubernetes pod.
You must provide a correct YAML installation file for the CNI plugin, but most ### Configure CLI access to UCP
of the default files work on Docker EE with no modification.
## YAML files for CNI plugins Next, a platform operator should log into UCP, download a UCP client bundle, and
configure the Kubernetes CLI tool, `kubectl`. See [CLI Based
Use the following commands to get the YAML files for popular CNI plugins. Access](ee/ucp/user-access/cli/#download-client-certificates) for more details.
- [Flannel](https://github.com/coreos/flannel) With `kubectl`, you can see that the UCP components running on
```bash Kubernetes are still pending, waiting for a CNI driver before becoming
# Get the URL for the Flannel CNI plugin. available.
CNI_URL="https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml"
```
- [Weave](https://www.weave.works/)
```bash
# Get the URL for the Weave CNI plugin.
CNI_URL="https://cloud.weave.works/k8s/net?k8s-version=Q2xpZW50IFZlcnNpb246IHZlcnNpb24uSW5mb3tNYWpvcjoiMSIsIE1pbm9yOiI5IiwgR2l0VmVyc2lvbjoidjEuOS4zIiwgR2l0Q29tbWl0OiJkMjgzNTQxNjU0NGYyOThjOTE5ZTJlYWQzYmUzZDA4NjRiNTIzMjNiIiwgR2l0VHJlZVN0YXRlOiJjbGVhbiIsIEJ1aWxkRGF0ZToiMjAxOC0wMi0wN1QxMjoyMjoyMVoiLCBHb1ZlcnNpb246ImdvMS45LjIiLCBDb21waWxlcjoiZ2MiLCBQbGF0Zm9ybToibGludXgvYW1kNjQifQpTZXJ2ZXIgVmVyc2lvbjogdmVyc2lvbi5JbmZve01ham9yOiIxIiwgTWlub3I6IjgrIiwgR2l0VmVyc2lvbjoidjEuOC4yLWRvY2tlci4xNDMrYWYwODAwNzk1OWUyY2UiLCBHaXRDb21taXQ6ImFmMDgwMDc5NTllMmNlYWUxMTZiMDk4ZWNhYTYyNGI0YjI0MjBkODgiLCBHaXRUcmVlU3RhdGU6ImNsZWFuIiwgQnVpbGREYXRlOiIyMDE4LTAyLTAxVDIzOjI2OjE3WiIsIEdvVmVyc2lvbjoiZ28xLjguMyIsIENvbXBpbGVyOiJnYyIsIFBsYXRmb3JtOiJsaW51eC9hbWQ2NCJ9Cg=="
```
If you have kubectl available, for example by using
[Docker Desktop for Mac](/docker-for-mac/kubernetes.md), you can use the following
command to get the URL for the [Weave](https://www.weave.works/) CNI plugin:
```bash
# Get the URL for the Weave CNI plugin.
CNI_URL="https://cloud.weave.works/k8s/net?k8s-version=$(kubectl version | base64 | tr -d '\n')"
```
- [Romana](http://docs.romana.io/)
```bash
# Get the URL for the Romana CNI plugin.
CNI_URL="https://raw.githubusercontent.com/romana/romana/master/docs/kubernetes/romana-kubeadm.yml"
```
## Disable IP in IP overlay tunneling
The Calico CNI plugin supports both overlay (IPIP) and underlay forwarding
technologies. By default, Docker UCP uses IPIP overlay tunneling.
If you're used to managing applications at the network level through the
underlay visibility, or you want to reuse existing networking tools in the
underlay, you may want to disable the IPIP functionality. Run the following
commands on the Kubernetes master node to disable IPIP overlay tunneling.
```bash ```bash
# Exec into the Calico Kubernetes controller container. $ kubectl get nodes
docker exec -it $(docker ps --filter name=k8s_calico-kube-controllers_calico-kube-controllers -q) sh NAME STATUS ROLES AGE VERSION
manager-01 NotReady master 10m v1.11.9-docker-1
# Download calicoctl
wget https://github.com/projectcalico/calicoctl/releases/download/v3.1.1/calicoctl && chmod +x calicoctl $ kubectl get pods -n kube-system -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE
# Get the IP pool configuration. compose-565f7cf9ff-gq2gv 0/1 Pending 0 10m <none> <none> <none>
./calicoctl get ippool -o yaml > ippool.yaml compose-api-574d64f46f-r4c5g 0/1 Pending 0 10m <none> <none> <none>
kube-dns-6d96c4d9c6-8jzv7 0/3 Pending 0 10m <none> <none> <none>
# Edit the file: Disable IPIP in ippool.yaml by setting "ipipMode: Never". ucp-metrics-nwt2z 0/3 ContainerCreating 0 10m <none> manager-01 <none>
# Apply the edited file to the Calico plugin.
./calicoctl apply -f ippool.yaml
``` ```
These steps disable overlay tunneling, and Calico uses the underlay networking, ### Install an unmanaged CNI Plugin
in environments where it's supported.
You can use`kubectl` to install a custom CNI plugin on UCP.
Alternative CNI plugins are Weave, Flannel, Canal, Romana and many more.
Platform operators have complete flexibility on what to install, but Docker
will not support the CNI plugin.
The steps for installing a CNI plugin typically include:
- Downloading the relevant upstream CNI binaries from
https://github.com/containernetworking/cni/releases/tag/
- Placing them in `/opt/cni/bin`
- Downloading the relevant CNI plugin's Kubernetes Manifest YAML, and
- Running `$ kubectl apply -f <your-custom-cni-plugin>.yaml`
Follow the CNI plugin documentation for specific installation
instructions.
> While troubleshooting a custom CNI plugin, you may wish to access logs
> within the kubelet. Connect to a UCP manager node and run
> `$ docker logs ucp-kubelet`.
### Verify the UCP installation
Upon successful installation of the CNI plugin, the related UCP components should have
a `Running` status as pods start to become available.
```
$ kubectl get pods -n kube-system -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE
compose-565f7cf9ff-gq2gv 1/1 Running 0 21m 10.32.0.2 manager-01 <none>
compose-api-574d64f46f-r4c5g 1/1 Running 0 21m 10.32.0.3 manager-01 <none>
kube-dns-6d96c4d9c6-8jzv7 3/3 Running 0 22m 10.32.0.5 manager-01 <none>
ucp-metrics-nwt2z 3/3 Running 0 22m 10.32.0.4 manager-01 <none>
weave-net-wgvcd 2/2 Running 0 8m 172.31.6.95 manager-01 <none>
```
> **Note**: The above example deployment uses Weave. If you are using an alternative
> CNI plugin, look for the relevant name and review its status.
## Where to go next ## Where to go next
- [Install UCP for production](../admin/install.md) - [Make your Cluster Highly Available](https://docs.docker.com/ee/ucp/admin/install/#step-6-join-manager-nodes)
- [Deploy a workload to a Kubernetes cluster](../kubernetes.md) - [Install an Ingress Controller on Kubernetes](ee/ucp/kubernetes/layer-7-routing/)