Gravitee.io Kubernetes Operator

Introduction

APIM 3.19.0 has introduced the Gravitee Kubernetes Operator (GKO) - a new technical component designed to be deployed on an existing APIM-ready Kubernetes Cluster. It can also be deployed on a local cluster for testing purposes.

You can use the GKO to define, deploy, and publish APIs to your API Portal and API Gateway and to manage Custom Resource Definitions (CRDs) as part of the process.

In future releases, the GKO will support additional functionality to enable the following:

• Using the GKO as an Ingress Controller for deploying Ingresses to an API Gateway.

• Deploying Gravitee products (API Management, Access Management, Alert Engine).

• Improving automation processes through covering CICD aspects when using Kubernetes with APIM.

• Managing most API Management resources without directly relying on the Console or on the Management API.

User documentation

You can find detailed information about the Gravitee Kubernetes Operator in the following sections of the Gravitee user documentation:

• Overview

• Architecture

• Quick Start

• Installation and deployment

• User Guide

The GKO API reference documentation is available link:{{ '/docs/api/reference.md' | relative_url }}[here].

Initialize you environment

• Install Docker

• Install kubectl

• Install Helm

• Install the operator-sdk: brew install operator-sdk

How to run locally

To run the operator locally against an APIM-ready k3d cluster, run the following commands:

# Initialize APIM locally using k3d
make k3d-apim-init

# Install CRDs into the K8s cluster specified in ~/.kube/config
make install

# Check that the Gravitee CRDs are available on your cluster
kubectl get crd

# Wait for APIM pods to become ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=apim3 --timeout 180s

# Run a controller from your host
make run

Try it

To create a basic API Definition, run following commands:

# Create a Management Context custom resource for your APIM instance running on k3d
kubectl apply -f ./config/samples/context/k3d/managementcontext_credentials_k3d.yaml

# Create a basic API Definition custom resource
kubectl apply -f ./config/samples/apim/basic-example-with-ctx.yml

kubectl get graviteeapis  -o wide
# NAME                ID                                     ENTRYPOINT   ENDPOINT                       VERSION   ENABLED
# basic-api-example   ff3549c9-ceb2-36da-87f7-f5e51ba89097   /k8s-basic   https://api.gravitee.io/echo   1.0       true

Deploying GKO as a k3d deployment

The following command will publish your Docker image to the k3d cluster registry, and deploy the operator in a dedicated gko-system namespace:

make k3d-gko-build k3d-gko-push k3d-gko-deploy

Contributing

Debugging with a locally running APIM

To be abble to run the operator against a local instance of both an APIM Gateway and an APIM Management API, you will need to:

• Attach to a local cluster context.

• Create a local service account to authenticate the gateway against the local cluster.

• Run both the APIM Gateway and the APIM Management API in debug mode.

• Create a Management Context custom resource pointing to your local APIM Management API.

# Create a service account token with 'cluster-admin' role in the current context and
# use this token to authenticate against the current cluster
make service-account

make run # or run using a debugger if you need to debug the operator as well

# Create the debug Management Context resource for APIM
kubectl apply -f ./config/samples/context/debug/managementcontext_credentials.yaml

# Create a basic API Definition resource
kubectl apply -f ./config/samples/apim/basic-example-with-ctx.yml

Testing and linting

To be able to run make lint and make install, install the following golang package:

go install gotest.tools/gotestsum@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Working with the repo

When committing your contributions, please follow conventional commits and semantic release best practices.

Troubleshooting

Note for Apple Silicon users

The default version of kustomize installed by the kustomize target is not available on arm64 platforms.

You can override the version to be used by setting the KUSTOMIZE_VERSION environment variable, as follows:

export KUSTOMIZE_VERSION=v4.5.5
make kustomize

Local Docker image registry

The k3d registry host used to share images between your host and your k3d cluster is defined as k3d-graviteeio.docker.localhost. On most linux / macos platforms, *.localhost` should resolve to 127.0.0.1. If this is not the case on your device, you need to add the following entry in your /etc/hosts file:

127.0.0.1 k3d-graviteeio.docker.localhost