Overboard: Hello world

In this tutorial we will create your first Overboard script and generate the Kubernetes YAML config to a file.

Requirements

1. A Kubernetes cluster to learn on such as Kubernetes on Docker or minikube.
2. A basic knowledge of using kubectl
3. dotnet SDK installed
4. Optionally, any IDE that supports F# (Visual Studio Code, IntelliJ Rider, Visual Studio, NeoVim)

Visual Studio Code with the Ionide is a great choice. See Setup your environment for more details.

Initial configuration

Create a F# script file called deployment.fsx

Copy the following code into the script file:

// TODO: import from Nuget
#r "nuget:Overboard"

// open the required namespaces
open Overboard
open Overboard.Common
open Overboard.Workload

// define your k8s config
let theInvalidDeployment = k8s {
    deployment {
        pod {
            container {
                name "nginx"
                image "nginx:latest"
                workingDir "/test-dir"
            }
        }
    }
}

// Write the YAML to infra.yaml file and get the list of validation issues
let validations = KubeCtlWriter.toYamlFile theInvalidDeployment "hello-world.yaml"
// Let's print out the validation errors
for err in validations do
    eprintfn "%s" err.Message

Output

"Deployment 'metadata.name' is required.
LabelSelector requires at least one of `matchLabels` or `matchExpressions`"

Now you can call the fsx file to generate your YAML config.

dotnet fsi deployment.fsx

If you run the apply command on your YAML file, you will see Kubernetes agrees with the validation errors.

kubectl apply -f hello-world.yaml

Fixed config

Let's address the validation errors that Overboard found.

1. Call the add_matchLabel operation with a key/value pair for the label.
2. Next, add the label to the pod using the _labels metadata operation, passing in a list of key/value pairs.

let theValidDeployment = k8s { 
    deployment {
        "test-deployment"
        replicas 2
        add_matchLabel ("app", "nginx") // <- fix the validation error
        pod {
            _labels [("app", "nginx")] // <- fix the validation error
            container {
                name "nginx"
                image "nginx:latest"
                workingDir "/test-dir"
            }
        }
    }
}

KubeCtlWriter.toYamlFile theValidDeployment "hello-world.yaml"

Output

Our validation errors are gone and we have a valid Kubernetes configuration.

"apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-deployment
  namespace: default
spec:
  minReadySeconds: 0
  progressDeadlineSeconds: 600
  replicas: 2
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      namespace: default
    spec:
      containers:
      - image: nginx:latest
        name: nginx
        resources:
          limits:
            cpu: 1000m
            memory: 512Mi
          requests:
            cpu: 500m
            memory: 256Mi
        workingDir: /test-dir
      restartPolicy: Always

"

Testing the result

Let's execute this deployment against our Kubernetes cluster to confirm it is indeed correct.

dotnet fsi deployment.fsx
kubectl apply -f hello-world.yaml
kubectl get deployments

You should get the message: deployment.apps/test-deployment created

Summary

In this tutorial you created your first Overboard script and generated the YAML. We saw how to get and print out the validation errors. Finally, we saw how we can successfully deploy our generated script.

Congratulations! You have taken a turn toward a new way of configuring your infrastructure.