README.md

Operator Resource Mapping

Previous ORM CRD and Samples are moved to archive, please find doc for compatibility here.

Table of Contents generated with DocToc

• Overview
  • Terminology
• Architecture
  • Core Controllers
  • Utility Controllers
• QuickStart
  • Step 1. Clone the repository
  • Step 2. Build and Run
    • Run locally
    • Other options
  • Step 3 Try Redis example
    • Prepare Standalone Redis
    • Apply OperatorResourceMapping for Redis
• Next Step

Overview

Operator Resource Mapping (ORM) is a map to allow assets like Kubeturbo to manage resources in an Operator managed Kubernetes cluster, for example to vertically scale containers or horizontally scale pods.

ORM works at operand basis, user defines which operand holds the desired status of which resources so that other assets can coordinate resource changes.

This repo provides new ORM resource scheme, legacy ORM CRD and examples are in archive folder. Controllers in this repo are

• helping users to compose and test ORMs with the operands and deployed resources only.
• generating ORM resource from legacy ORM resources for backward compatibility

Terminology

Advisor: Tools providing recommendations to workloads (e.g. Turbonomic, HorizontalPodAutoscaler, VerticalPodAutoScaler). In this phase 1, Advisor can get the mapping from ORM resource and modify the owner for recommendation.

Owner: the operator resource who owns actual deployed resources. Changes in owner trigger operator to update deployed/owned resources

Owned resource: resources deployed by operator, answer to changes in operand/owner

Mapping: pair of paths in owner and owned resources

Pattern: pair of paths in owner and owned resource. Parameters can be defined in patters in order to generate multiple mapping from one pattern.

Selectors: predefined label selectors to be reused in patterns

Parameters: predefined list of strings for mapping generation

Predefined Parameters - all predefined parameters starts with "."

• .owned.name: refer to the name of the owned resource. Together with label selector of owned resource, a pattern can generate lots of mappings if the naming is right.

Architecture

System architecture is described in the figure below:

Core Controllers

ORM Controller – watch ORM resource and update registry with mappings

Mapper Ownership – retrieve value from owner resource and update ORM status

Utility Controllers

Compatibility Controller - Generate new ORM from legacy ORM

QuickStart

ORM leverages operator sdk to create/build project, follow the standard operator sdk approach to run it locally or generate images to deploy to a target cluster with right RBAC settings.

Step 1. Clone the repository

mkdir turbonomic
cd turbonomic
git clone https://github.com/turbonomic/orm.git
cd orm

Step 2. Build and Run

Run locally

You're able to run the orm controllers if you have access to a kubernetes cluster. Please ensure the rbac of your current access is able to cover the resources you want map.

make install run

You terminal is occupied by the controller after it is started, you need to start another terminal to try examples

Other options

Feel free to try other approaches in Operator SDK such as OLM deployment, Direct deployment.

Step 3 Try Redis example

Prepare Standalone Redis

In order to show relationship between operator and the resource it manages we use Redis operator from OT_CONTAINER-KIT. We created redis standalone.

helm list -A

NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                      APP VERSION
redis           ot-operators    1               2023-05-04 12:27:31.051399 -0400 EDT    deployed        redis-0.14.2           0.14.0     
redis-operator  ot-operators    1               2023-03-13 12:31:40.264923 -0400 EDT    deployed        redis-operator-0.14.3      0.14.0     

Apply OperatorResourceMapping for Redis

Apply the redis standalone orm from library and you can see the pattern defined in spec are located in the cluster. Details are showed in status.

kubectl get orm -n ot-operators redis-orm -o yaml

apiVersion: devops.turbonomic.io/v1alpha1
kind: OperatorResourceMapping
metadata:
  name: redis-orm
  namespace: ot-operators
...
spec:
  mappings:
    patterns:
    - owned:
        apiVersion: apps/v1
        kind: StatefulSet
        path: .spec.template.spec.containers[?(@.name=="redis")].resources
        selector: my_redis_sts
      ownerPath: .spec.kubernetesConfig.resources
    selectors:
      my_redis_sts:
        matchLabels:
          app: redis
  owner:
    apiVersion: redis.redis.opstreelabs.in/v1beta1
    kind: Redis
    name: redis
status:
  lastTransitionTime: "2023-05-04T17:27:05Z"
  owner:
    apiVersion: redis.redis.opstreelabs.in/v1beta1
    kind: Redis
    name: redis
    namespace: ot-operators
  ownerValues:
  - owned:
      apiVersion: apps/v1
      kind: StatefulSet
      name: redis
      namespace: ot-operators
      path: .spec.template.spec.containers[?(@.name=="redis")].resources
    ownerPath: .spec.kubernetesConfig.resources
    value:
      resources: {}
  state: ok

Next Step

In the phase 2 of this project, we're introducing more Advice Mapping related controllers to automate changes from community assets. Details are described here