Skip to main content

Krateo Core Provider

The Krateo Core Provider is the foundational component of Krateo Composable Operations (KCO), enabling the management of Helm charts as Kubernetes-native resources. It provides:

  • Schema validation through JSON Schema
  • Automated CRD generation
  • Versioned composition management
  • Secure authentication mechanisms

Summary

Glossary

  • CRD (Custom Resource Definition): A Kubernetes resource that defines custom objects and their schemas, enabling users to extend Kubernetes functionality.
  • CompositionDefinition: A custom resource in the core-provider that defines how Helm charts are managed and deployed in Kubernetes.
  • CDC (Composition Dynamic Controller): A controller deployed by the core-provider to manage resources defined by a CompositionDefinition. This controller is responsible to create, update, and delete helm releases and their associated resources based on the values defined in the composition
  • Helm Chart: A package of pre-configured Kubernetes resources used to deploy applications.
  • OCI Registry: A container registry that supports the Open Container Initiative (OCI) image format, used for storing and distributing Helm charts.
  • RBAC Policy: A set of rules that define permissions for accessing Kubernetes resources. Typically composed of roles, role bindings, cluster roles, and cluster role bindings assigned to service accounts.
  • values.schema.json: A JSON Schema file included in Helm charts to define and validate the structure of values.yaml.

Architecture

core-provider Architecture Image

This diagram outlines the high-level architecture and interactions within the Core Provider, responsible for managing CompositionDefinitions and related resources. It illustrates the relationships between key components such as the Core Provider itself, the Composition Dynamic Controller (CDC), the Chart Inspector, and various Kubernetes resources.

The Core Provider generates CRDs, creates RBAC policies, and deploys the CDC. The CDC manages Helm chart releases, requests resource information from the Chart Inspector, and generates RBAC policies based on those resources. The diagram highlights the flow of definitions and resources between these components, showcasing how the Core Provider orchestrates the deployment and management of composed applications within a Kubernetes cluster.

Workflow

![core-provider State Diagram]((/img/core-provider-flow.png "core-provider State Diagram")

This diagram illustrates the Core Provider's workflow for managing CompositionDefinitions, which define how resources are composed and managed in a Kubernetes environment. It encompasses the lifecycle of Helm releases and associated resources, involving the creation and updating of CRDs (Custom Resource Definitions), RBAC (Role-Based Access Control), and CDC (Composition Dynamic Controller) deployments. These actions are conditional, based on chart versions and the current state of the cluster.

Note: The kubectl commands within the notes serve as illustrative examples of the operations performed by the Core Provider and are not intended for direct user execution. They provide insights into the resource management processes undertaken by the system.

Requirements

The core-provider does not requires Snowplow anymore to be installed in the cluster. The core-provider is now able to retrieve resource plurals from the cluster without Snowplow. This change was introduced in version 0.24.2 of the core-provider.

CompositionDefinition specifications and examples

The core-provider is a Kubernetes operator that downloads and manages Helm charts. It checks for the existence of values.schema.json and uses it to generate a Custom Resource Definition (CRD) in Kubernetes, accurately representing the possible values that can be expressed for the installation of the chart.

Kubernetes is designed to validate resource inputs before applying them to the cluster, and the core-provider provides input validation to ensure that incorrect inputs are not accepted.

Authentication

The core-provider also handles authentication to private OCI registries and Helm repositories. Users can provide their credentials through Kubernetes secrets, and the core-provider will use them to download the necessary chart resources.

OCI Registry

Create the Kubernetes secret:

kubectl create secret generic docker-hub --from-literal=token=your_token -n krateo-system
apiVersion: core.krateo.io/v1alpha1
kind: CompositionDefinition
metadata:
annotations:
"krateo.io/connector-verbose": "true"
name: fireworks-private
namespace: krateo-system
spec:
chart:
url: oci://registry-1.docker.io/yourusername/fireworks-app
version: "0.1.0"
credentials:
username: yourusername
passwordRef:
key: token
name: docker-hub
namespace: krateo-system
GCP Artifact Registry

Follow this guide to create a service account key. You will need to download the .json file containing the key and create the Kubernetes secret from it. Note that the service account should have permissions to download from the Google Artifact Registry.

Now, create a secret from the JSON file containing your service account key:

kubectl create secret generic gcp-sa-secret -n demo \
--from-file=secret-access-credentials=/path/to/file/krateoregistry-3d546566ae4a.json
apiVersion: core.krateo.io/v1alpha1
kind: CompositionDefinition
metadata:
name: fireworks-private
namespace: krateo-system
spec:
chart:
url: oci://europe-west12-docker.pkg.dev/krateoregistry/krateotest/fireworks-app
version: "0.0.1"
credentials:
username: json_key
passwordRef: # reference to a secret
key: secret-access-credentials
name: gcp-sa-secret
namespace: demo

Note: The spec.chart.credentials.username should be set to json_key as explained in this documentation.

Helm Repository

kubectl create secret generic helm-repo --from-literal=token=your_token -n krateo-system
apiVersion: core.krateo.io/v1alpha1
kind: CompositionDefinition
metadata:
annotations:
"krateo.io/connector-verbose": "true"
name: fireworks-private
namespace: krateo-system
spec:
chart:
repo: fireworks-app
url: https://theurltoyourhelmrepo
version: 0.3.0
credentials:
username: yourusername
passwordRef:
key: token
name: helm-repo
namespace: krateo-system

Composition Definition

A Composition is a Helm Chart archive (.tgz) with a JSON Schema for the values.yaml file. The JSON Schema file must be named values.schema.json.

Here are some online tools to generate and validate JSON Schemas:

CRD Specification

To view the CRD configuration, visit this link.

How to Install

You can install the core-provider with the following commands:

helm repo add krateo https://charts.krateo.io
helm repo update
helm install krateo-core-provider krateo/core-provider --namespace krateo-system --create-namespace

Examples and Troubleshooting

You can see a more practical guide on core-provider usage at this link.

Environment Variables and Flags

NameDescriptionDefault ValueNotes
HELM_REGISTRY_CONFIG_PATHPath to Helm registry configuration file/tmp/.config/helm/registry/config.jsonUsed for OCI registries
CORE_PROVIDER_DEBUGEnables debug loggingfalseUse --debug flag
CORE_PROVIDER_SYNCSync period for controller manager1hDuration
CORE_PROVIDER_POLL_INTERVALPoll interval for resource drift checks5mDuration
CORE_PROVIDER_MAX_RECONCILE_RATEMaximum reconcile rate per second3Integer
CORE_PROVIDER_LEADER_ELECTIONEnables leader election for controller managerfalseUse --leader-election flag
CORE_PROVIDER_MAX_ERROR_RETRY_INTERVALMaximum retry interval on errors1mDuration
CORE_PROVIDER_MIN_ERROR_RETRY_INTERVALMinimum retry interval on errors1sDuration
URL_PLURALSNOT USED from version 0.24.2 - URL to krateo pluraliser servicehttp://snowplow.krateo-system.svc.cluster.local:8081/api-info/namesString

Security Features

  • Generates CRDs based on the chart's schema, preventing invalid configurations
  • Deploys composition-dynamic-controller with minimal necessary permissions
  • Removes RBAC policies upon deletion of the CR
  • Implements mutating webhook and conversion webhook for enhanced security and flexibility

Best Practices

  1. Always include a values.schema.json file in your Helm charts
  2. Use the krateo.io/paused annotation to manage composition lifecycle
  3. Leverage the multi-version support for smooth upgrades and rollbacks

By implementing these improvements and best practices, the Krateo Core Provider offers enhanced flexibility, security, and version management capabilities for Kubernetes-based applications.