Installing CDK manually
The recommended way to install the Charmed Distribution of Kubernetes ® is using the conjure-up install tool as described in the 'Quick start' documentation. However, in some cases it may be useful to customise the install in ways not possible with conjure-up:
- Adding additional components
- Configuring storage or networking
- Copying an existing configuration
- Testing a pre-release version
- ...and many more
In many cases, using the bundle install method outlined here will be faster and more repeatable than customising a deployment post-install.
This documentation first presents the method for installing from the official release bundles, then explains how the bundle can be customised.
Install CDK from the official bundle
The following sections outline a standard installation of CDK using the stable release Juju bundles. The standard bundle includes all the components of Kubernetes, but you should also follow the additional configuration steps at the end for Kubernetes to be able to interact with the cloud it is deployed on.
If Juju has not already been installed on your system, you need to install it first. For Ubuntu 16.04 and later, and other operating systems which support snaps, run the command:
sudo snap install juju --classic
For other install options, please see the Juju documentation.
Create a controller
Juju requires a controller instance to manage models and deployed applications. You can make use of a hosted controller (JAAS) or create one in a cloud of your choice. For public clouds, you will need to have added a credential first:
...will step through adding your credential for a specific cloud.
Create a model
The controller automatically creates a model named 'default'. It is useful to
have a different model for each deployment of CDK, and for the models to have
useful names. You can create a new model with the
add-model command like
juju add-model cdk-test
...susbstituting the desired name.
Deploy the CDK bundle
The Juju Charm Store hosts the CDK bundles as well as individual charms. To deploy the latest, stable bundle, run the command:
juju deploy charmed-kubernetes
To get the status of the deployment, run
juju status. For constant updates,
combine it with the
watch -c juju status --color
It is also possible to deploy a specific version of the bundle by including the revision number. For example, to deploy the CDK bundle for the Kubernetes 1.13 release, you could run:
juju deploy cs:~containers/canonical-kubernetes-435
Previous versions of CDK used the name
canonical-kubernetes. These versions are still available under that name
and links in the charm store. Versions from 1.14 onwards will use
The revision numbers for bundles are generated automatically when the bundle is updated, including for testing and beta versions, so it isn't always the case that a higher revision number is 'better'. The revision numbers for the release versions of the CDK bundle are shown in the table below:
|Kubernetes version||CDK bundle|
Note: Only the latest three versions of CDK are supported at any time.
You will need kubectl to be able to use your Kubernetes cluster. If it is not already installed, it is easy to add via a snap package:
sudo snap install kubectl --classic
For other platforms and install methods, please see the Kubernetes documentation.
The config file for accessing the newly deployed cluster is stored in the cluster itself. You should use the following command to retrieve it:
juju scp kubernetes-master/0:config ~/.kube/config
Caution: If you have multiple clusters you will need to manage the config file rather than just replacing it. See the Kubernetes documentation for more information on managing multiple clusters.
You can verify that kubectl is configured correctly and can see the cluster by running:
You can now continue to operate your cluster. If you are new to CDK or Kubernetes, you should check out the Basic operations documentation, which will explain how to get familiar with your cluster. For further customisation options, including cloud integration, continue reading below first.
To allow Kubernetes to access resources and functionality of the underlying cloud upon which it is deployed, additional integrator charms are available. When installing with conjure-up, these charms are automatically added to the deployment and configured appropriately.
Adding the integrator charms directly with Juju is not recommended - it is more reliable (and easier) to include these charms at deployment time, using the "overlay" method as described below. The manual deployment steps shown here are only for reference to give a better understanding of how these charms work in relation to CDK.
This table explains which charms are used:
|Cloud||Integrator charm||Juju deploy command||Notes/docs|
|AWS||aws-integrator||juju deploy cs:~containers/aws-integrator||docs|
|Azure||azure-integrator||juju deploy cs:~containers/azure-integrator||docs|
|gcp-integrator||juju deploy cs:~containers/gcp-integrator||docs|
|OpenStack||openstack-integrator||juju deploy cs:~containers/openstack-integrator||docs|
|Rackspace||openstack-integrator||juju deploy cs:~containers/openstack-integrator||docs|
|vSphere||vsphere-integrator||juju deploy cs:~containers/vsphere-integrator||docs|
The charm should be deployed and relationships established with both the
kubernetes-master charms. For example, in the case of
juju deploy cs:~containers/aws-integrator juju trust aws-integrator juju add-relation aws-integrator kubernetes-master juju add-relation aws-integrator kubernetes-worker
juju trust command allows the aws-integrator to make use of the
credentials stored by Juju.
This demonstrates how the charm relates to the rest of the CDK bundle, but it is recommended to use the overlay method for installing in practice.
Customising the bundle install
A number of the scenarios outlined at the start of this document involved customising the CDK install. There are two main ways to do this, using overlays or editing the bundle file itself.
Using an overlay means you can easily apply your customisation to different versions of the CDK bundle, with the possible downside that changes in the structure of new versions of CDK may render your overlay obsolete or non-functional (depending on what exactly your overlay does).
Saving a copy of the CDK bundle file and editing that means that your customisation will always work, but of course, requires that you create a new file for each version of CDK.
Both methods are described below.
A bundle overlay is a fragment of valid YAML which is dynamically merged on
top of a bundle before deployment, rather like a patch file. The fragment can
contain any additional or alternative YAML which is intelligible to Juju. For
example, to replicate the steps used above to deploy and connect the
aws-integrator charm, the following fragment could be used:
applications: aws-integrator: charm: cs:~containers/aws-integrator num_units: 1 relations: - ['aws-integrator', 'kubernetes-master'] - ['aws-integrator', 'kubernetes-worker']
You can also download the fragment here.
Juju's bundle format, and valid YAML are discussed more fully in the Juju documentation. In this example it merely adds a new application, specifying the charm to use, and further specifies the relationships to add.
To use this overlay with the CDK bundle, it is specified during deploy like this:
juju deploy charmed-kubernetes --overlay ~/path/aws-overlay.yaml
Substitute in the local path and filename to point to your YAML fragment.
Note that you will still need to run the command to share credentials with this charm:
juju trust aws-integrator
Adding or changing constraints
After adding additional components, the most common use of overlays is to change constraints (the resources requested for the application). Although these are specified already in the CDK bundle, they can be overridden by an overlay. It isn't necessary to replicate the entirety of an entry, just the parts you wish to change. For example:
kubernetes-worker: constraints: cores=4 mem=8G root-disk=100G num_units: 6
Changes the machine constraints for Kubernetes workers to add more root disk space, and also deploys six units instead of the three specified in the original bundle.
More information on the constraints you can use is available in the Juju documentation.
Changing configuration values
Configuration settings are mapped to "options" under the charm entries in the bundle
YAML. Usually these are only expressed when they differ from the default value in the
charm. For example, if you look at the fragment for the
kubernetes-worker in the
kubernetes-worker: annotations: gui-x: '100' gui-y: '850' charm: cs:~containers/kubernetes-worker-398 constraints: cores=4 mem=4G root-disk=16G expose: true num_units: 3 options: channel: 1.13/stable resources: cni-amd64: 12 cni-arm64: 10 cni-s390x: 11 kube-proxy: 0 kubectl: 0 kubelet: 0
...there is only one entry under 'options', in this case for the snap channel to use. There are however, a number of configuration options available (more details are in the charm documentation). We can add additional configuration by supplying the desired settings under options. So, for example, where we might do the following through Juju to set some proxy values:
juju config kubernetes-worker https_proxy=https://proxy.example.com juju config kubernetes-worker snap_proxy:=https://snap-proxy.example.com
... we can instead use the following YAML fragment as an overlay:
kubernetes-worker: options: https_proxy: https://proxy.example.com snap_proxy: https://snap-proxy.example.com
Editing a bundle
Another way to change or customise an install is to store the YAML bundle file locally and edit it with a standard text editor.
The latest version of the CDK bundle can always be retrieved by fetching the current stable version from the Juju Charm Store. For other versions, see the table above.
Care should be taken when editing the YAML file as the format is very strict. For more details on the format used by Juju, see the Juju bundle documentation.
Retrieving a bundle from a running model
Sometimes a more convenient way of getting a local bundle file which matches exactly the deployment you want is simply to save a running model as a bundle. This will preserve configuration, relations and the charms used in the deployment so a structural replica can be recreated.
This can be done simply by running the command:
juju export-bundle --filename mybundle.yaml
The resulting YAML file will be downloaded to the current working directory.
It is also possible to view, edit and export bundles from the Juju GUI:
Running this command will output some login information and a URL for the GUI
interface (the GUI actually runs on the Juju controller instance). On visiting
the URL given and logging in, a graphical representation of the current model
will be shown. To export the model as a YAML bundle, click on the
button near the top left of the screen.
For more information on the Juju GUI, see the Juju documentation.