Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

'Hello, World' tutorial with Kubernetes Operators

August 21, 2020
Deepak Sharma
Related topics:
DevOpsGoKubernetesOperators
Related products:
Red Hat OpenShift

Share:

    Kubernetes Operators reduce the work of human operators or site reliability engineers. Rather than a half-baked definition, I refer you to this original definition from the creators of the Kubernetes Operator Framework: Operators are Kubernetes applications.

    When I started building Operators with the operator-sdk I discovered several unknowns that were difficult to address. I decided to create a guided introduction to the Kubernetes Operator SDK.

    Hang on tight.

    Note: For a more recent version of this article, see Build a Kubernetes Operator in six steps.

    Getting started with Kubernetes Operators

    Developers use the Kubernetes Operator SDK to make and deploy complex applications in Kubernetes. In this article, for the sake of brevity and understanding, we will create a simple, namespace-scoped Operator in Golang. We will build a deployment and set up a service. We'll also create a custom controller reconciliation loop that will watch over our deployed resources.

    The prerequisites for this guided journey are as follows:

    • Be familiar with any programming language, though knowledge of Golang will be helpful for this example.
    • Have Minikube installed in your development environment

    Set up your environment

    We will start by installing the utilities we need to build the Operator.

    Set up Golang

    We will use Golang to build the Operator. Install Golang, and then configure the following environment settings, as well as any other settings that you prefer:

    $GOPATH=/your/preferred/path/
    $GO111MODULE=on
    

    Next, verify the installation:

    # Verify
    $ go version
    go version go1.13.3 linux/amd64
    

    Set up the SDK

    We will use the Kubernetes Operator SDK to build our Operator. Install the Operator SDK, then verify the installation:

    # Verify
    $ operator-sdk version
    operator-sdk version: "v0.17.0", commit: "2fd7019f856cdb6f6618e2c3c80d15c3c79d1b6c", kubernetes version: "unknown", go version: "go1.13.10 linux/amd64"
    

    Build the Operator

    In this section, we'll build the Operator. After each instruction, I will share the file tree for the example so far. Please verify the file tree at each step to ensure that you are in sync with the example.

    Generate the example application code

    Head over to $GOPATH/src/operators and run:

    $ operator-sdk new hello-operator
    

    This command generates the boilerplate code for our example application. The default Operator type is GO.

    At this point, your file tree should look like this.

    Add a custom resource definition

    We use custom resource definitions (CRDs) to introduce custom resources that are understandable by k8s deployments. The CRD for this example is as follows:

    $ operator-sdk add api --api-version=example.com/v1alpha1 --kind=Traveller
    

    Note that we use api-versionto connect to the example application's namespace Operator. The format is group/version. The kind definition refers to custom kind for the application example. It will be used by the custom resources (CRs) that we create next.

    Your file tree should now look like this.

    Update the custom resources

    Specifications (specs) are like hardcoded configuration values, also known as the desired state of the cluster. In order to create the specs for this example, we will edit the custom resources in two files.

    Update example.com_v1alpha1_traveller_cr.yaml

    In this file, we can add any custom values that we might need for our controller function. Here, we will add the Hello Kubernetes image created by Paul Bouwer. Figure 1 shows the updated file, which you can find at deploy > crds > example.com_v1alpha1_traveller_cr.yaml.

    A screenshot of the example.com_v1alpha1_traveller_cr.yaml file.

    Figure 1: Add custom values for the controller function.">

    Update traveller_types.go

    We use this file to bring custom values to the controllers. The variables are case sensitive, so keep the title case for all variables. For example:

    {Variable} {type} {json:"name in *_cr.yaml" }

    Figure 2 shows the updates to bring custom values to the controllers. This file should be in pkg > apis > example > v1aplha1 > traveller_types.go.

    A screenshot of the traveller_types.go file.
    Figure 2: Add custom values to the controllers.

    To update the generated code for the given resource type, run the following:

    $ operator-sdk generate k8s
    

    After each edit in *_types.go, you must update the CRD to add Open API validations against the newly introduced values. This process is completely automated, simply by entering the following command:

    $ operator-sdk generate crds
    

    You should now see this diff.

    Add the controller

    Controllers define the reconciliation logic and the cluster resources to watch. Any change in a resource that is being watched triggers a reconciliation in the controller. Here is the command to add the controller to your Operator SDK:

    >$ operator-sdk add controller --api-version=example.com/v1alpha1 --kind=Traveller

    As always, verify the code diff before moving on.

    We added the controller with default settings, namely the default APIs, role-based access control (RBAC), and service accounts. Next, we will add the custom logic for creating the application deployment and services. Whatever logic we write should be idempotent.

    Add custom logic to the Operator SDK

    We will add five custom functions to the Operator SDK:

    • backendDeployment: Deploys the pod and exposes it at port 8080.
    • backendService: Creates a new back-end service for the exposed port.
    • ensureDeployment: Ensures the presence of a deployment in the given namespace. Otherwise, it creates a deployment by calling 1.
    • ensureService: Ensures the back-end service is present and running in the given namespace. Otherwise, it creates the service by calling 2.
    • labels: Sets the labels on the deployment and pods.

    Change the reconcile function to trigger the newly defined functions.

    Your code diff should now look like this.

    Test the Operator locally

    We are done adding our custom logic and building up the functionality. Now, we will test the Operator locally:

    # Please deploy in Sequence only
    $ kubectl apply -f deploy/role.yaml
    $ kubectl apply -f deploy/service_account.yaml
    $ kubectl apply -f deploy/role_binding.yaml
    $ kubectl apply -f deploy/crds/example.com_travellers_crd.yaml
    $ kubectl apply -f deploy/crds/*_cr.yaml
    

    Assuming that all of the above artifacts deploy successfully, we can run the Operator locally:

    $ operator-sdk run up --local
    

    This command should start up the Operator. Make sure that all of the custom resources are deployed by checking them against the namespace. For brevity, we're using the default namespace:

    $ kubectl get all

    The results are shown in Figure 3 where k is an alias for kubectl.

    Kubernetes resources deployed in the default namespace
    Figure 3: Get all Kubernetes resources deployed in the default namespace.

    Test the service

    Finally, test the service in Minikube by opening up a tunnel:

    $ minikube service backend-service
    

    The results are shown in Figure 4.

    Minikube by opening up a tunnel

    Figure 4: Get endpoint for backend-service deployed in Minikube.">

    The Minikube tunnel should redirect us to the service that we just created:

    A screenshot of the home screen for the 'Hello, world' Kubernetes application

    Figure 5: Home screen for the 'Hello, world' Kubernetes application.">

    And that's it! You have just developed a basic Kubernetes Operator.

    Export the Operator

    For a real cluster deployment, you would also need to export the Operator:

    $ operator-sdk build docker_username/repo:v0.0.1
    $ docker push docker_username/repo
    $ sed -i "" 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml
    $ kubectl apply -f deploy/operator.yaml
    

    Once you export the Operator, you can publish it via Git or Source Control Management (SCM), zip and mail it, or whatever you need to do.

    Conclusion

    I again want to emphasize that Operators exist to simplify complex application deployments on Kubernetes. Operators especially support day-to-day activities like upgrading and downgrading Kubernetes applications and more. The guided exercise in this article is a good starting point for working with Operators. See the references below to learn more. Also, check out the GitHub repository for this tutorial, Basic Operator for Beginners, which includes the complete example code for this article.

    Further references

    These additional references are useful for learning about Kubernetes Operators and the Operator Framework:

    • Kubernetes Operators: Automating the Container Orchestration Platform (O'Reilly, April 2020)
    • Source code for the example application used in this article, Hello Kubernetes!
    Last updated: September 19, 2023

    Related Posts

    • Build a Kubernetes Operator in six steps

    • 5 tips for developing Kubernetes Operators with the new Operator SDK

    • Kubernetes Operators in Depth

    Recent Posts

    • More Essential AI tutorials for Node.js Developers

    • How to run a fraud detection AI model on RHEL CVMs

    • How we use software provenance at Red Hat

    • Alternatives to creating bootc images from scratch

    • How to update OpenStack Services on OpenShift

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue