# Getting Started

# Prerequisites

It's time to create your first operator. But before you proceed, make sure you're up-to-date on all the important KUDO concepts:

# Package Structure

Our first operator will deploy Nginx to the cluster. If you're thinking that one doesn't need a KUDO operator to do this, you're absolutely right. It hardly showcases KUDOs strong sides but this is a hello-world type of operator and we have to start somewhere.

Create a new folder ./first-operator that will contain the operator (also known as a local package bundle). The overall structure of a package looks following:

.
├── operator.yaml
├── params.yaml
└── templates
    └── deployment.yaml

The operator.yaml is the main YAML file defining both operator metadata as well as the whole lifecycle of the operator. params.yaml defines parameters of the operator. During installation, these parameters can be overridden allowing customization. templates folder contain all templated Kubernetes objects that will be applied to your cluster after installation based on the workflow defined in operator.yaml.

# Operator Substance

First let’s create an operator.yaml file in the ./first-operator.

apiVersion: kudo.dev/v1beta1
name: "first-operator"
operatorVersion: "0.1.0"
appVersion: "1.7.9"
kubernetesVersion: 1.13.0
maintainers:
  - name: Your name
    email: <your@email.com>
url: https://kudo.dev
tasks:
  - name: app
    kind: Apply
    spec:
      resources:
        - deployment.yaml
plans:
  deploy:
    strategy: serial
    phases:
      - name: main
        strategy: parallel
        steps:
          - name: everything
            tasks:
              - app

This is an operator with just one plan deploy, which has one phase and one step and represents the minimal setup. The deploy plan is automatically triggered when you install an instance of this operator into your cluster.

You can see that the task app references the resource deployment.yaml. KUDO expects this file to exist inside the templates folder. As the next step, create templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: {{ .Params.replicas }} # tells deployment to run 2 pods matching the template
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:{{ .AppVersion }}
          ports:
            - containerPort: 80

This is a pretty normal Kubernetes YAML file defining a deployment. However, you can already see the KUDO templating language in action on the line referencing .Params.replicas. This will get substituted during installation by merging what is in params.yaml and overrides defined before install. So let’s define the last missing piece, params.yaml (which goes into the root first-operator folder next to operator.yaml).

apiVersion: kudo.dev/v1beta1
parameters:
  - name: replicas
    description: Number of replicas that should be run as part of the deployment
    default: 2

Now your first operator is ready and you can install it to your cluster. You can do this by invoking kubectl kudo install ./first-operator where ./first-operator is a relative path to the folder containing your operator. To do this, you need to have the KUDO CLI installed - follow the instructions here, if you haven't already. Various resources will be installed for your operator, among them Operator, OperatorVersion and Instance, as described in, What is KUDO.

In order to see what's happen in your cluster you can run the following command:

# Get Instances
kubectl get instances

# OR
kubectl kudo get instances

If all worked fine, you should see 2 pods running

kubectl get pods

# Testing Your Operator

You should aim for your operators being tested for day 1. To help you with testing your operator, we have developed a tool called test harness (it's also what we use to test KUDO itself). For more information please go to test harness documentation.

# What's Next

Take a look at the Pipe-Tasks and learn how to create a custom index.html starting page in a separate step of the deploy plan and start your Nginx with it.

← What is KUDO Anatomy of an Operator →