# Examples
# KUDO Init
KUDO itself is a Kubernetes operator. As such it requires the installation of CRDs and the deployment of KUDO, in addition to the establishment of certain prerequisites like creating the namespace to install in. All of this can be handled by the KUDO CLI. To accomplish this, run kubectl kudo init
. Some variations on this might include:
kubectl kudo init --wait --wait-timeout 600
which will install CRDS, install KUDO and will wait up to 600 seconds for KUDO to be responsive.kubectl kudo init --dry-run --output=yaml > kudo-install.yaml
which will not install anything but will output YAML to a file which can be applied manually to the server.kubectl kudo init --version=0.10.0
which will install the0.10.0
version in the cluster using thekudobuilder/controller:v0.10.0
imagekubectl kudo init --kudo-image=mycompany/controller:v0.6.0
allowing for user certified images or air-gapped alternative images to be installed.kubectl kudo init --client-only
which will not apply any changes to the cluster. It will setup the default KUDO home with repository options.kubectl kudo init --crd-only
will create crds in the cluster.
Any admission controller in Kubernetes is an HTTPS endpoint and thus requires a valid certificate. KUDO relies on the cert-manager 0.11 or higher for this. You should have cert-manager installed (opens new window) and operational prior to admission controller installation. Read more about the admission controllers and how/why KUDO uses them to ensure correct plan execution.
As an alternative you can use kudo init --unsafe-self-signed-webhook-ca
to install KUDO into your cluster with a self signed CA for the webhook. This is very useful for local testing but should not be used for production setups.
Note: Looking to delete kubernetes objects created via init, run:
kubectl kudo init --dry-run -o yaml | kubectl delete -f -
which will delete all kubernetes objects created with init orkubectl kudo init --dry-run -o yaml --crd-only | kubectl delete -f -
which will only delete the KUDO CRDs.
# Install a Package
There are four options how to install a package. For development you can install packages from your local filesystem or local tgz file. For testing, or working without a repository, it is possible to install from a URL. Another option is to install from the package repository.
Installation during development can use a relative or absolute path to the package folder.
kubectl kudo install pkg/kudoctl/bundle/testdata/zk
To support the installation of operators not yet in the repository, it is possible to install directly from a URL.
kubectl kudo install http://kudo.dev/zk.tgz
For normal operations it is recommended to use the official packages provided through the kudobuilder/operators (opens new window) repository. To install official Kafka package you have to do the following:
kubectl kudo install kafka
Both of these options will install new instance of that operator into your cluster. By default, the instance name will be generated.
kubectl kudo install kafka --app-version=2.4.0
This will install new instance of Kafka Operator which maps to Kafka app version 2.4.0
kubectl kudo install kafka --operator-version=1.2.0
This will install new instance of Kafka Operator which maps to Kafka operator version 1.2.0
# Install a Package Overriding Instance Name and Parameters
Use --instance
for setting an instance name.
Use --parameter
/-p
and/or --parameter-file
/-P
for setting parameters.
For example:
$ cat kafka-parameters.yaml
ZOOKEEPER_URI: zk-zk-0.zk-hs:2181,zk-zk-1.zk-hs:2181,zk-zk-2.zk-hs:2181
ZOOKEEPER_PATH: /small
$ kubectl kudo install kafka --instance=my-kafka-name -p BROKER_COUNT=3 -P kafka-parameters.yaml
operator.kudo.dev/kafka unchanged
operatorversion.kudo.dev/kafka unchanged
instance.kudo.dev/v1alpha1/my-kafka-name created
$ kubectl get instances
NAME AGE
my-kafka-name 6s
# Get Instances
You can use the get
command to get a list of all current instances:
kubectl kudo get instances --namespace=<default> --kubeconfig=<$HOME/.kube/config>
Example:
$ kubectl kudo get instances
List of current instances in namespace "default":
.
├── small
├── up
└── zk
This maps to the kubectl
command:
kubectl get instances
Example:
$ kubectl kudo get instances
NAME CREATED AT
small 4d
up 3d
zk 4d
# Get the Status of an Instance
Now that you have a list of available instances, you can get the current status of all plans for one of them:
kubectl kudo plan status --instance=<instanceName> --kubeconfig=<$HOME/.kube/config>
Note: The --instance
flag is mandatory.
$ kubectl kudo plan status --instance=up
Plan(s) for "up" in namespace "default":
.
└── up (Operator-Version: "upgrade-v1" Active-Plan: "up-deploy-493146000")
├── Plan deploy (serial strategy) [COMPLETE]
│ └── Phase par (serial strategy) [COMPLETE]
│ └── Step run-step (COMPLETE)
├── Plan update (serial strategy) [NOT ACTIVE]
│ └── Phase par (serial strategy) [NOT ACTIVE]
│ └── Step par (serial strategy) [NOT ACTIVE]
│ └── run-step [NOT ACTIVE]
└── Plan upgrade (serial strategy) [NOT ACTIVE]
└── Phase par (serial strategy) [NOT ACTIVE]
└── Step par (serial strategy) [NOT ACTIVE]
└── run-step [NOT ACTIVE]
In this tree chart you see all important information in one screen:
up
is the instance you specified.default
is the namespace you are in.upgrade-v1
is the instance's Operator-Version.up-deploy-493146000
is the current Active-Plan.par
is a serial phase within thedeploy
plan which isCOMPLETE
.deploy
is aserial
plan which isCOMPLETE
.run-step
is aserial
step which isCOMPLETE
.
update
is anotherserial
plan that is currentlyNOT ACTIVE
.par
is a serial phase within theupdate
plan which isNOT ACTIVE
.par
is aserial
collection of steps which isNOT ACTIVE
.run-step
is aserial
step within thepar
step collection which isNOT ACTIVE
.
upgrade
is anotherserial
plan which is currentlyNOT ACTIVE
.par
is a serial phase within theupgrade
plan which isNOT ACTIVE
par
is aserial
collection of steps which isNOT ACTIVE
.run-step
is aserial
step within thepar
step collection which isNOT ACTIVE
.
For comparison, the according kubectl
commands to retrieve the above information are:
kubectl get instances
(to get the matchingOperatorVersion
)kubectl describe operatorversion upgrade-v1
Here, you can find the overview of all available plans in Spec.Plans
of the matching OperatorVersion
:
$ kubectl describe operatorversion upgrade-v1
Name: upgrade-v1
Namespace: default
Labels: controller-tools.k8s.io=1.0
Annotations: kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"kudo.dev/v1alpha1","kind":"OperatorVersion","metadata":{"annotations":{},"labels":{"controller-tools.k8s.io":"1.0"},"name":"upgra...
API Version: kudo.dev/v1alpha1
Kind: OperatorVersion
Metadata:
Cluster Name:
Creation Timestamp: 2018-12-14T19:26:44Z
Generation: 1
Resource Version: 63769
Self Link: /apis/kudo.dev/v1alpha1/namespaces/default/operatorversions/upgrade-v1
UID: 30fe6209-ffd6-11e8-abd5-080027d506c7
Spec:
Connection String:
Operator:
Kind: Operator
Name: upgrade
Parameters:
Default: 15
Description: how long to have the container sleep for before returning
Display Name: Sleep Time
Name: SLEEP
Required: false
Plans:
Deploy:
Phases:
Name: par
Steps:
Name: run-step
Tasks:
run
Strategy: serial
Strategy: serial
Update:
Phases:
Name: par
Steps:
Name: run-step
Tasks:
run
Strategy: serial
Strategy: serial
Upgrade:
Phases:
Name: par
Steps:
Name: run-step
Tasks:
run
Strategy: serial
Strategy: serial
Tasks:
Run:
Resources:
job.yaml
Templates:
Job . Yaml: apiVersion: batch/v1
kind: Job
metadata:
namespace: default
name: {{PLAN_NAME}}-job
spec:
template:
metadata:
name: {{PLAN_NAME}}-job
spec:
restartPolicy: OnFailure
containers:
- name: bb
image: busybox:latest
imagePullPolicy: IfNotPresent
command:
- /bin/sh
- -c
- "echo {{PLAN_NAME}} for v1 && echo Going to sleep for {{SLEEP}} seconds && sleep {{SLEEP}}"
Version: 1.0.0
Events: <none>
# Delete an Instance
You can delete an instance (i.e. uninstall it from the cluster) using kubectl kudo uninstall --instance <instanceName>
. The deletion of an instance triggers the removal of all the objects owned by it.
# History of Plan Executions
This is helpful if you want to find out which plan ran on your instance to a particular OperatorVersion
.
Run this command to retrieve all plans that ran for the instance up
and its OperatorVersion upgrade-v1
:
$ kubectl kudo plan history upgrade-v1 --instance=up
History of plan-executions for "up" in namespace "default" to operator-version "upgrade-v1":
.
└── up-deploy-493146000 (created 4h56m12s ago)
Run this command to retrieve the history of all plans applied to an instance:
$ kubectl kudo plan history --instance=up
History of all plan-executions for "up" in namespace "default":
.
└── up-deploy-493146000 (created 4h52m34s ago)
This includes the previous history but also all OperatorVersions that have been applied to the selected instance.
# Package an Operator
You can use the package create
command to package an operator into a tarball. The package name will be determined by the operator metadata in the package files. The folder of the operator is passed as an argument. It is possible to pass a --destination
location to build the tgz file into.
kubectl kudo package create zookeeper --destination=target
Example:
$ kubectl kudo package create ../operators/repository/zookeeper/operator/ --destination=~
Package created: /Users/kensipe/zookeeper-0.1.0.tgz
# Validating an Operator
You can use the package verify
command to check the condition of an operator which returns warnings and errors. Warnings are conditions such as a parameter is defined in the params.yaml but is not used a template file. Errors are conditions such as a parameter is used in a template file but is not defined in the params.yaml. If there are errors the command exits with a non-zero exit code.
Examples:
$ kubectl kudo package verify ../operators/repository/zookeeper/operator/
package is valid
$ kubectl kudo package verify ../operators/repository/kafka/operator/
Warnings
parameter "SSL_ENDPOINT_IDENTIFICATION_ENABLED" defined but not used.
parameter "CUSTOM_SERVER_PROPERTIES" defined but not used.
package is valid
# Create a Repository Index File
A repository is a set of operator packages (tarballs) which are indexed in an index file. To create an index file, execute kubectl kudo repo index operators
where operators
is a folder container operator package files.
# example folder
ls ~/repo
kafka-2.2.1-0.1.2.tgz kafka-0.2.0.tgz
# repo index
kubectl kudo repo index ~/repo
index /Users/kensipe/repo/index.yaml created.
cat ~/repo/index.yaml
apiVersion: v1
entries:
kafka:
- digest: f81ffdad2caea40c8fc19c676b1e51b598d1472de5563c0ae8308e649c8ea159
maintainers:
- name: Zain Malik <zmalikshxil@gmail.com>
name: kafka
operatorVersion: 0.2.0
urls:
- http://localhost/kafka-0.2.0.tgz
- appVersion: 2.2.1
digest: fbff9679cd0070bf10dcafc8d5e1e7d13a5c1651154165162c543508895a37c0
maintainers:
- name: Zain Malik <zmalikshxil@gmail.com>
name: kafka
operatorVersion: 0.1.2
urls:
- http://localhost/kafka-2.2.1-0.1.2.tgz
It can be useful when overwriting a file to use --overwrite
. It is also useful to use --url=http://kudo.dev/repo
to supply the desired URL the operator packages will be hosted on.
# Managing Repositories
After KUDO has initialized a client, kubectl kudo init
or kubectl kudo init --client-only
, it is possible to configure other repositories. Let's start with a repo list
using:
kubectl kudo repo list
NAME URL
*community https://kudo-repository.storage.googleapis.com
The default installation shown shows one repository configured with the name "community". The *
indicates that this is the default repository to use (unless the flag --repo=xyz
is used). This is considered the current context.
When a repository is added using kudo add ...
, the url provided will be used to access the index.yaml file which will be validated. If the url is not reachable or the index file is corrupt the repository entry will fail to be added. It is possible to skip this check with the --skip-check
flag. You can add a repository in the following way. kubectl kudo repo add local http://localhost --skip-check
. Resulting in:
kubectl kudo repo list
NAME URL
*community https://kudo-repository.storage.googleapis.com
local http://localhost
In order to set the local repository as the current context execute: kubectl kudo repo context local
, resulting in:
kubectl kudo repo list
NAME URL
community https://kudo-repository.storage.googleapis.com
*local http://localhost
Now all installs and upgrades will default to the local repository.
In order to remove a repository simply run kubectl kudo repo remove foo
# Update Parameters on Instance
Every operator can define overridable parameters in params.yaml
. When installing an operator and deploying an instance, you can use the defaults or override them with -p
or -P
parameters to kudo install
.
The kudo update
command allows you to change these parameters even on an already running operator instance. For example, if you have an instance in your cluster named dev-flink
(you can figure out what you have installed with kubectl get instances
) and that operator exposes a parameter with the name param
, you can change its value with the following command:
kubectl kudo update --instance dev-flink -p param=value
# Upgrade Instance from One Version to Another
Following the same example from the previous section, having a dev-flink
instance installed, we can upgrade it to a newer version with the following command:
kubectl kudo upgrade flink --instance dev-flink -p param=xxx
A new version of that operator is installed to the cluster and upgrade
(or deploy
) plan is started to roll out new Flink pods.
At the same time, we're overriding the value of the parameter param
. That is optional and you can always do it in a separate step via kudo update
.
# Collecting diagnostic data
With an existing installation of an operator, it is possible to collect diagnostic data:
kubectl kudo diagnostics collect --instance dev-flink --log-since 10m
This command will create a new directory and collect the following data:
- The KUDO environment:
- The installed manager and its logs
- Service accounts and services
- The data for the specified operator
- The Operator, OperatorVersion and Instance resources
- The deployed resources from the operator
- The logs from deployed pods - Limited by the specified
--log-since
parameter