rest-dynamic-controller

Rest Dynamic Controller

The rest-dynamic-controller is an operator instantiated by the oasgen-provider to manage Custom Resources whose Custom Resource Definitions (CRDs) are generated by the oasgen-provider.

Extended and detailed information about the overall setup and usage of the oasgen-provider and rest-dynamic-controller can be found in the oasgen-provider README. It is recommended to refer to that document as this README is just a concise summary focused on the rest-dynamic-controller.

Table of Contents

• Overview
• How It Works
• Architecture
• Usage Examples
• Configuration

Overview

The rest-dynamic-controller is a dynamic controller that manages Remote Resources through REST APIs. It's considered "dynamic" because it can manage any type of remote resource represented by a Custom Resource Definition and its related Custom Resource. The controller is configured at startup through environment variables (or CLI parameters) to manage a specific Group Version Resource.

How It Works

When a Custom Resource (CR) is created and its Custom Resource Definition (CRD) has been generated by a RestDefinition from the oasgen-provider, the following process occurs:

1. The rest-dynamic-controller instance checks if the remote resource exists by following the instructions defined in the RestDefinition.
2. If the resource doesn't exist, the controller performs the action described in the verbsDescription field of the RestDefinition CR.
3. For deletion requests, a similar process is followed.
4. During resource observation, the controller verifies if the remote resource is synchronized with the CR and performs updates if necessary.

Architecture

Standard scenario

flowchart LR

  subgraph Generator
  provider[oasgen-provider]
  restdefinition[[RestDefinition Manifest]]
  crd[[CRD Manifest]]
  end

  subgraph Dynamic_Controller["Dynamic Controller"]
  rdc[rest-dynamic-controller]
  cr[[Custom resource Manifest]]
  end

  er[(External Resource)]

  restdefinition -.->|Definition for| provider

  provider -->|Generate| crd

  provider -->|Deploy| rdc

  cr -.->|Definition for| rdc

  rdc -->|"Manage (Observe, Create, Update, Delete)"| er

  cr -.->|Instance of| crd

Scenario with Plugin (Wrapper Web Service)

flowchart LR

  subgraph Generator
  provider[oasgen-provider]
  restdefinition[[RestDefinition Manifest]]
  crd[[CRD Manifest]]
  end

  subgraph Dynamic_Controller["Dynamic Controller"]
  rdc[rest-dynamic-controller]
  cr[[Custom resource Manifest]]
  end

  er[(External Resource)]

  restdefinition -.->|Definition for| provider

  provider -->|Generate| crd

  provider -->|Deploy| rdc

  cr -.->|Definition for| rdc

  rdc --> |"Manage (Observe, Create, Update, Delete)"| ws[Plugin <br>Wrapper Web Service]

  ws --> er

  cr -.->|Instance of| crd

Usage Examples

Here's an example of a Custom Resource manifest:

apiVersion: github.ogen.krateo.io/v1alpha1
kind: Repo
metadata:
  name: test-repo1
  namespace: default
  annotations:
    krateo.io/connector-verbose: "true"
spec:
  configurationRef:
    name: my-repo-config
    namespace: default 
  org: krateoplatformops
  name: test-repo1

This manifest represents a CR of kind Repo with apiVersion github.ogen.krateo.io/v1alpha1.

Additionally, the configuration resource for the above CR can be defined as follows:

apiVersion: github.ogen.krateo.io/v1alpha1
kind: RepoConfiguration
metadata:
  name: my-repo-config
  namespace: default
spec:
  authentication:
    bearer:
      # Reference to a secret containing the bearer token
      tokenRef:
        name: gh-token        # Name of the secret
        namespace: default    # Namespace where the secret exists
        key: token            # Key within the secret that contains the token

The CRDs for Repo and RepoConfiguration were generated by the oasgen-provider based on the specifications in the RestDefinition shown below.

kind: RestDefinition
apiVersion: ogen.krateo.io/v1alpha1
metadata:
  name: repo
spec:
  oasPath: configmap://repo-ns/repo/repo.yaml
  resourceGroup: github.ogen.krateo.io
  resource: 
    kind: Repo
    additionalStatusFields:
      - name
      - id
      - html_url
    verbsDescription:
    - action: create
      method: POST
      path: /orgs/{org}/repos
    - action: delete
      method: DELETE
      path: /repos/{org}/{name}
    - action: get
      method: GET
      path: /repos/{org}/{name}
    - action: update
      method: PATCH
      path: /repos/{org}/{name}

Configuration

Environment Variables

The following environment variables can be configured in the rest-dynamic-controller's Deployment: