CLI Usage

Setting up a Kubernetes cluster on OpenStack and Rancher requires a lot of configuration details. Ironik uses a template file to hold said configurations that must be filled out before anything can be deployed.

First run the following command to receive a blank template:

$ ironik template

This creates the file ironik_template.yaml in the local directory. Open this file with a text editor.

Filling out the template

The template has multiple sections: - deployment_options - kubernetes_config - network_config - openstack_config - openstack_credentials - rancher_config - rancher_credentials

Deployment options are used to configure the validation of the cluster once it is setup.

This is not implemented yet and can be ignored for now.

Kubernetes config allows setting the number of master and worker nodes to deploy as well as what roles they should have.

Furthermore, the version of Kubernetes can be set here.

master_node_roles lists all the roles the master nodes should have. This can be mostly left as it is unless master nodes should, for example, not have the worker role.

number_master_nodes is the number of master nodes to deploy initially. This can be changed later via Rancher.

number_worker_nodes is the number of worker nodes to deploy initially. This can be changed later via Rancher.

version is the Kubernetes version to be deployed. The version must be available in the Rancher instance used and exactly match the version string there.

worker_node_roles lists all the roles the worker nodes should have. This should usually be left as just worker.

Network config describes what ports should be opened in the security group created in OpenStack.

It also allows setting the port range that Kubernetes is allowed to use. These can be left as it is as the list of ports is based on the Rancher documentation and what ports it requires.

required_TCP_ports sets the TCP ports to open in the security group. These should usually be left alone. Additional ports can later be opened in the security group in OpenStack.

required_UDP_ports sets the UDP ports to open in the security group. These should usually be left alone. Additional ports can later be opened in the security group in OpenStack.

worker_port_range_max sets the high end of the ports that Kubernetes can use. This is both set in the OpenStack security group as well as in the Kubernetes settings.

worker_port_range_min sets the low end of the ports that Kubernetes can use. This is both set in the OpenStack security group as well as in the Kubernetes settings.

OpenStack config needs to be filled out for the deployment to work.

default_flavor_name is the flavor to use for the nodes in OpenStack. OpenStack web UI -> Compute -> Instances -> Launch Instance -> Flavor, for example: ‘m1.medium’

default_image_name is the image to use for the nodes in OpenStack. OpenStack web UI -> Compute -> Images, for example: ‘Ubuntu 20.04.3 Server x86_64 (ssd)’

lb_provider is the load balancer system deployed in OpenStack. OpenStack web UI -> Network -> Load Balancers -> Create a new load balancer and check what is set as its provider. Common lb_provider are amphora, octavia or in older systems haproxy.

openstack_auth_url is the authentication endpoint to use for OpenStack. OpenStack web UI -> API access -> Identity, append “/v3” to it.

private_network_id is the private network into which the nodes should be deployed. OpenStack web UI -> Network -> select Networks -> pick a private network -> select overview -> ID

project_domain_name is the domain of the project in OpenStack. OpenStack web UI -> Identity -> Projects -> Domain Name

region_name is the region used by OpenStack. This is usually “RegionOne”.

remote_ip_prefix is the IP mask for the IPs used inside the OpenStack network. This can be for example 10.254.1.0/24.

security_group_name sets the name of the security group in OpenStack to create. If this groups already exist, it will be deleted and recreated.

use_octavia determines whether to use the Octavia load balancer in OpenStack. Should Octavia not be installed, set this to false.

user_domain_name is the domain used when logging in to OpenStack. Often its the same as the project_domain_name

volume_size sets the size of volumes to be created for each node in OpenStack. If set to 0 no volumes will be created.

volume_type sets the type of volume to use in OpenStack. OpenStack web UI -> Volumes -> Volumes -> Create Volume, see the available types.

Next are the OpenStack credentials.

password is the OpenStack password used to login. project_id is the OpenStack project id.

OpenStack web UI -> Identity -> Projects -> Project ID

username is the OpenStack username used to login.

Rancher config set configuration on for Rancher.

engine_install_url is the url from where the docker engine install script should be fetched. This can be left as it is.

new_cluster_admin_user_name is the name of the user who should be admin of the new cluster in Rancher. If the user does not exist, it will be created.

new_cluster_admin_user_password is the password of the user who should be admin of the new cluster. If it is left empty, it will be created. If the user already exist, it will be ignored.

rancher_api_base_url is the url used to access the Rancher API. It is commonly the base web address of the Rancher instance with “/v3” at the end.

ssh_user`is the name of the default ssh user for new nodes in OpenStack. This might be `root or cloud depending on the OpenStack instance.

Rancher credentials are the Rancher API credentials.

rancher_access_key is the access key part of the Rancher API key.

rancher_secret_key is the secret key part of the Rancher API key. The Rancher API key must be unscoped and can be created via the Rancher web interface.

Starting deployment

Once the template has been filled out it can be used to start a deployment.

$ ironik deploy cluster_name ./ironik_template.yaml

Replace cluster_name with the desired name for the new cluster.

Ironik will test out the credentials and check whether enough resources are available in OpenStack. Then it reports said information in a table and asks for confirmation.

After confirming the start of the deployment it will create the node templates in Rancher, the cluster in Rancher and wait for the cluster to deploy.

After the cluster is ready it will attempt to create a new user and print the generated password into the console if a new user was created.

Afterwards Ironik will apply the manifests used to install the OpenStack controller manager and the Cinder driver.