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.

Install Juju

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:

juju add-credential

…will step through adding your credential for a specific cloud.

The Juju documentation has more information on adding credentials and configuring a controller.

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 this:

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 command:

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

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:

Configure kubectl

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

You can verify that kubectl is configured correctly and can see the cluster by running:

kubectl cluster-info

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.

Additional configuration

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:

The charm should be deployed and relationships established with both the kubernetes-worker and kubernetes-master charms. For example, in the case of AWS:

juju deploy cs:~containers/aws-integrator
juju trust aws-integrator
juju add-relation aws-integrator kubernetes-master
juju add-relation aws-integrator kubernetes-worker

The 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.

Using overlays

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 CDK bundle:

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:

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 Export button near the top left of the screen.

For more information on the Juju GUI, see the Juju documentation.