diff --git a/_data/toc.yaml b/_data/toc.yaml index 130bf78530..1371623a34 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -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/ diff --git a/ee/ucp/admin/install/index.md b/ee/ucp/admin/install/index.md index 3070c1bf58..5fece24ed2 100644 --- a/ee/ucp/admin/install/index.md +++ b/ee/ucp/admin/install/index.md @@ -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 diff --git a/ee/ucp/kubernetes/install-cni-plugin.md b/ee/ucp/kubernetes/install-cni-plugin.md index b3b7e024ac..ce3b1a3838 100644 --- a/ee/ucp/kubernetes/install-cni-plugin.md +++ b/ee/ucp/kubernetes/install-cni-plugin.md @@ -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 \ - --unmanaged-cni \ + --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 +compose-api-574d64f46f-r4c5g 0/1 Pending 0 10m +kube-dns-6d96c4d9c6-8jzv7 0/3 Pending 0 10m +ucp-metrics-nwt2z 0/3 ContainerCreating 0 10m manager-01 ``` -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 .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 +compose-api-574d64f46f-r4c5g 1/1 Running 0 21m 10.32.0.3 manager-01 +kube-dns-6d96c4d9c6-8jzv7 3/3 Running 0 22m 10.32.0.5 manager-01 +ucp-metrics-nwt2z 3/3 Running 0 22m 10.32.0.4 manager-01 +weave-net-wgvcd 2/2 Running 0 8m 172.31.6.95 manager-01 +``` + +> **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/)