Kopgen

Welcome to the Kopgen documentation. This project helps you generate Kubernetes Custom Resource Definitions (CRDs) and operators from a standard OpenAPI Specification using Rust.

Table of Contents

1. Introduction
2. Getting Started
3. Configuration
4. Usage
5. Examples
6. Contributing
7. License

Architecture Overview

graph TD
    A[OpenAPI Specification] -->|Input| B[Kopgen]
    B -->|Generates| C[Kubernetes CRDs / Schema]
    B -->|Generates| D[Kubernetes Operator]
    C -->|Deploys to| E[Kubernetes Cluster]
    D -->|Deploys to| E[Kubernetes Cluster]
    D -->|Manages| F[Kubernetes Resources]
    D -->|Syncing / Reconciles| G[External API Resources]

Getting Started

This guide will help you get started with the Kopgen tool.

Prerequisites

• Visual Studio Code
• Docker

Installation

Clone the repository and navigate to the project directory:

git clone https://github.com/edenreich/kopgen.git
cd kopgen

Setting Up the Development Environment

1. Open Visual Studio Code.
2. Open the cloned repository directory in Visual Studio Code.
3. When prompted, open the project in a DevContainer. If not prompted, you can manually open the DevContainer by pressing Ctrl+Shift+P and selecting Remote-Containers: Reopen in Container - this will set up the development environment with all the necessary dependencies and tools.

Configuration

This project uses a DotEnv file for configuring the CPU architecture the operator should be built for, as well as the container registry and cluster to connect to.

Please refer to the .env.example file to see what environment variables are available. When you are just getting started, you can copy it to a .env file and keep it as-is.

Here is the list of the environment variables available:

By default, the configuration points to a local environment, and a local cluster will be created using ctlptl with k3d. Please review the Cluster.yaml file:

---
apiVersion: ctlptl.dev/v1alpha1
kind: Registry
name: ctlptl-registry
port: 5005
---
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: k3d
registry: ctlptl-registry

As for the operator configurations, you can configure the following using custom OpenAPI attributes:

info:
  x-kubernetes-operator-group: "example.com"
  x-kubernetes-operator-version: "v1"
  x-kubernetes-operator-resource-ref: "uuid"
  x-kubernetes-operator-example-metadata-spec-field-ref: "name"
  x-kubernetes-operator-include-tags:
    - cats
    # - dogs
    # - horses

Usage

This tool operates on a straightforward principle: the OpenAPI Specification is the single source of truth. Any adjustments or changes should be made directly in the OpenAPI Specification, eliminating the need for any code modifications.

Assuming you have an API running somewhere, you most likely have also an OpenAPI Specification file, which defining all of the endpoints of your API (if you don't, please search on YouTube for the following Documentation Driven Development with OpenAPI, there are a lot of tutorials how to write a Swagger / OpenAPI files).

This tool will read the OpenAPI Specification you give it and will generate the Operator along aside with its Kubernetes Custom Resource Definition (CRD's) including the necessary Role Based Access Control (RBAC) policies, to ensure the operator is only maintaining resources from the given resource groups.

Based on the Endpoints configured in the OpenAPI Specification the tool will know what type of operation needs to be implemented in code. As an example if you have a POST endpoint, the tool will generate the necessary code for creating your data model on the API endpoint, if it's a PUT, the tool will generate the update code and so on and so forth.

If your OpenAPI Specification does not include a Delete endpoint, a warning will appear in the operator logs when you attempt to delete the Kubernetes CRD, indicating that the Delete operation is not implemented.

This tool is coming in the form of a CLI that you can run in the terminal, the CLI is located in crates/k8s-codegen and it's built using Clap.

To see the available commands run:

cargo run --package k8s_codegen generate --help

You should see the following output:

Usage: k8s_codegen generate [OPTIONS]

Options:
  -a, --all
  -l, --lib
  -m, --manifests
  -c, --controllers
  -t, --types
  -h, --help         Print help

You can either generate the code along aside with everything, or generate only the specifics.

For simplicity, let's generate everything, run:

cargo run --package k8s_codegen generate --all

Note that 2 crates are completely generated after running this command, you should see crates/k8s-crdgen and crates/k8s-operator.

The crate k8s-crdgen is a simple rust code that translates to a binary which generating the Kubernetes CRD's out of the Rust data models.

The crate k8s-operator contains the actual code that uses the CRD's and executes the Create, Read, Update and Delete (CRUD) operations.

You can also use the Taskfile located in the root directory and instead run:

task oas-generate-rust-client
task oas-generate-docs
task generate-code
task generate-crds

Or run just:

task generate

Which will run all the above commands at once.

To list the available tasks you can run:

task --list

After working with the existing openapi.yaml file, which is a dummy one. Feel free to change it with your actual API and regenerate everything by, deleting the generated code:

rm -rf crates/{k8s-crdgen,k8s-operator,client-sdk}

Comment out temporarily the workspaces in the root Cargo.toml and replace the openapi.yaml with your actual API and run:

task generate

To troubleshoot errors with your OpenAPI Spec, you can also run:

task oas-validate

Please also provide examples in your OpenAPI Specification because these will help you generate the example CRD's for testing purposes.

Examples

Contributing

License

This project is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at: Apache License, Version 2.0

Permissions

The Apache 2.0 license allows you to:

• Use: You can use the code for any purpose.
• Modify: You can modify the code and create derivative works.
• Distribute: You can distribute the original code or your modifications.
• Patent Use: The license provides an express grant of patent rights from contributors.

Conditions

When using the code, you must:

• Include the License: You must include a copy of the Apache 2.0 license in any distribution of the code.
• State Changes: If you modify the code, you must include a prominent notice stating that you have changed the files.
• Provide a Notice: You must include a notice in your documentation or source code that refers to the Apache 2.0 license.

Limitations

The Apache 2.0 license comes with the following limitations:

• No Warranty: The code is provided "as is", without warranty of any kind, express or implied.
• Liability: The license limits the liability of contributors.

For more detailed information, please refer to the full text of the Apache License, Version 2.0.