Language SDKs

The Flux Operator has the start of language SDKs that can be used to interact with MiniCluster objects and a deployed MiniCluster. This should guide will walk you through some of the developer basics.

Python

Setup

The Python sdk is generated by way of the following steps:

  • We start with an operator-sdk API definition in Go files (the content of api/v1alpha)

    • The labels “+k8s:openapi-gen=true” and similar tags are needed to generate Go Swagger file

  • The openapi-gen tool (added to bin by the Makefile) turns your Go types files into a single Go file with a spec (zz_generated.openapi.go)

    • Always check for validation errors from that tool if you make any changes to the api documents (see below for how to generate)

  • You then use a small Go script to write that into a swagger Json (hack/python-sdk/main.go)

    • This script Does a print of the names, and any that are from external libraries, name to something else

  • We prepared a swagger_config.json (in hack/python-sdk/) with metadata and these “something else” imports

  • Files are generated into sdk/python/v1alpha1 (or other API version)

  • Tests are done in both sdk/python/v1alpha1/test (provided by the generator) and tests/python (testing operator functionality too)

For a detailed walk through of this setup, see this blog post that walks through that.

File Generation

By default, anything that already exists in sdk/python/v1alpha can be over-written, and for the automated files in “model” or “api” or “test” we want that to be the case. However, for a subset of files that would be overwritten, they are copied after the build from hack/python-sdk/template into the root of the Python install directory. This means, for example, to update the setup.py you should update it in the hack folder, as the one in the distributed folder will be overwritten. For files that aren’t overwritten (e.g., extra modules added to the fluxoperator model or the docs/README.md or examples) you can make changes directly in the generated directory.

Practical Steps

  1. Make changes to template files that will be written over in hack/python-sdk/template

  2. Make changes to module files that aren’t overwritten directly in sdk/python/v1alpha

  3. With any changes to the Flux Operator, build the Python API with make api or make pre-push

For the last step, this typically means that you can make updates automatically to the API by way of:

$ make api

A courtesy command is also provided to build the api and the flux-operator.yaml:

$ make pre-commit

The idea being that right before a push you should be rebuilding the API and deployment YAml.

Last update: Nov 05, 2024