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/
- title: Create a service account for a Kubernetes app
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/
- title: 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
[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,
> like Flannel or Weave, modify the previous command line to include the
> `--cni-installer-url` option. Learn how to
> [install a CNI plugin](../../kubernetes/install-cni-plugin.md).
> UCP will install [Project Calico](https://docs.projectcalico.org/v3.7/introduction/)
> for container-to-container communication for Kubernetes. A platform operator may
> choose to install an alternative CNI plugin, such as Weave or Flannel. Please see
>[Install an unmanaged CNI plugin](/ee/ucp/kubernetes/install-cni-plugin/).
{: important}
## Step 5: License your installation

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

@ -1,98 +1,119 @@
---
title: Install a CNI plugin
description: Learn how to install a Container Networking Interface plugin on Docker Universal Control Plane.
keywords: ucp, cli, administration, kubectl, Kubernetes, cni, Container Networking Interface, flannel, weave, ipip, calico
title: Install an unmanaged CNI plugin
description: Learn how to install a Container Networking Interface (CNI) plugin on Docker Universal Control Plane.
keywords: ucp, kubernetes, cni, container networking interface, flannel, weave, calico
---
For Docker Universal Control Plane, [Project Calico](https://docs.projectcalico.org/v3.0/introduction/)
provides the secure networking functionality for the container communication with Kubernetes.
For Docker Universal Control Plane (UCP), [Calico](https://docs.projectcalico.org/v3.7/introduction/)
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
built-in [Calico](https://github.com/projectcalico/cni-plugin) plugin, but you can override that and
install a Docker certified plugin.
At install time, UCP can be configured to install an alternative CNI plugin
to support alternative use cases. The alternative CNI plugin is certified by
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)
to add the `--cni-installer-url` [option](/reference/ucp/3.0/cli/install.md),
providing a URL for the location of the CNI plugin's YAML file:
This command will install UCP, and bring up components
like the user interface and the RBAC engine. UCP components that
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
docker container run --rm -it --name ucp \
-v /var/run/docker.sock:/var/run/docker.sock \
{{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} install \
--host-address <node-ip-address> \
--unmanaged-cni <true|false> \
--unmanaged-cni \
--interactive
```
> **Note**: Setting `--unmanaged-cni` to `true` value installs UCP without a managed CNI plugin. UCP and the
> Kubernetes components will be running but pod-to-pod networking will not function until a CNI plugin is manually
> installed. This will impact some functionality of UCP until a CNI plugin is running.
Once the installation is complete, you will be able to access UCP in the browser.
Note that the manager node will be unhealthy as the kubelet will
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
of the default files work on Docker EE with no modification.
### Configure CLI access to UCP
## YAML files for CNI plugins
Use the following commands to get the YAML files for popular CNI plugins.
- [Flannel](https://github.com/coreos/flannel)
```bash
# Get the URL for the Flannel CNI plugin.
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.
Next, a platform operator should log into UCP, download a UCP client bundle, and
configure the Kubernetes CLI tool, `kubectl`. See [CLI Based
Access](ee/ucp/user-access/cli/#download-client-certificates) for more details.
With `kubectl`, you can see that the UCP components running on
Kubernetes are still pending, waiting for a CNI driver before becoming
available.
```bash
# Exec into the Calico Kubernetes controller container.
docker exec -it $(docker ps --filter name=k8s_calico-kube-controllers_calico-kube-controllers -q) sh
# Download calicoctl
wget https://github.com/projectcalico/calicoctl/releases/download/v3.1.1/calicoctl && chmod +x calicoctl
# Get the IP pool configuration.
./calicoctl get ippool -o yaml > ippool.yaml
# Edit the file: Disable IPIP in ippool.yaml by setting "ipipMode: Never".
# Apply the edited file to the Calico plugin.
./calicoctl apply -f ippool.yaml
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
manager-01 NotReady master 10m v1.11.9-docker-1
$ kubectl get pods -n kube-system -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE
compose-565f7cf9ff-gq2gv 0/1 Pending 0 10m <none> <none> <none>
compose-api-574d64f46f-r4c5g 0/1 Pending 0 10m <none> <none> <none>
kube-dns-6d96c4d9c6-8jzv7 0/3 Pending 0 10m <none> <none> <none>
ucp-metrics-nwt2z 0/3 ContainerCreating 0 10m <none> manager-01 <none>
```
These steps disable overlay tunneling, and Calico uses the underlay networking,
in environments where it's supported.
### Install an unmanaged CNI Plugin
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
- [Install UCP for production](../admin/install.md)
- [Deploy a workload to a Kubernetes cluster](../kubernetes.md)
- [Make your Cluster Highly Available](https://docs.docker.com/ee/ucp/admin/install/#step-6-join-manager-nodes)
- [Install an Ingress Controller on Kubernetes](ee/ucp/kubernetes/layer-7-routing/)