kpt Documentation on kpt documentation

Mon, 01 Jan 0001 00:00:00 +0000

FAQ #

What is the roadmap for kpt? #

Please visit the roadmap GitHub Project and the kpt milestones.

How is kpt different from other solutions? #

Think of configuration as an API or data in a database. kpt can operate on configuration in storage, git or OCI.

Rather than expressing configuration AS code or templates that generate configuration, kpt represents Configuration as Data. In particular, it represents configuration as YAML or JSON objects adhering to The Kubernetes Resource Model, the same as the live state in Kubernetes, which enables novel remedies to configuration drift.

Mon, 01 Jan 0001 00:00:00 +0000

Tenant onboarding #

Warning

This guide is a work in progress and may not fully reflect the current state of kpt. It is due for a rewrite.

We have seen that in large organizations using kubernetes, there is a platform team (or infrastructure team) that is responsible for managing the kubernetes clusters. Typically a kubernetes cluster is shared by multiple teams to run different types of workloads. One of the common use-cases platform teams have is onboarding a new tenant on the kubernetes cluster. In this guide, you will learn - how you can use kpt to address the tenant use-case. Though this guide focuses on the tenant use-case, the pattern for package workflow discussed here can be applied to other use cases as well.

Mon, 01 Jan 0001 00:00:00 +0000

Value propagation pattern #

Generating a string value and propagating that value to another place (or many other places) in your configuration is a very common pattern. In this guide, we will go through the recommended technique to do this value propagation using our starlark and apply-replacements KRM functions.

String generation function #

Sometimes, the value that we need to propagate is a concatenation of other values that come from various other resource fields. In order to generate the value we need to propagate, we can make use of the starlark function.

Mon, 01 Jan 0001 00:00:00 +0000

Variant construction pattern #

If you look at the config workflows, you will notice that creating a variant of a package is a very frequent operation, so reducing the steps required to create a variant can have significant benefits for the package consumers. In this guide, we will look at some techniques that a package author can use to enable automatic variant construction of a package.

Types of packages #

kpt packages comes in two flavors: abstract package and deployable instance. An abstract package is a reususable package that is used to create deployable instances that can be deployed to a kubernetes cluster. In programming language terms, you can think of an abstract packages as the class and deployable instance as the instances of the class. deployable instances of package are also referred to as variant of the package.

Mon, 01 Jan 0001 00:00:00 +0000

Installation #

Users can get kpt CLI in a variety of ways:

Binaries #

Download pre-compiled binaries:

curl -LO https://github.com/kptdev/kpt/releases/download/v1.0.0/kpt_linux_amd64-1.0.0.tar.gz

curl -LO https://github.com/kptdev/kpt/releases/download/v1.0.0/kpt_linux_arm64-1.0.0.tar.gz

curl -LO https://github.com/kptdev/kpt/releases/download/v1.0.0/kpt_darwin_amd64-1.0.0.tar.gz

curl -LO https://github.com/kptdev/kpt/releases/download/v1.0.0/kpt_darwin_arm64-1.0.0.tar.gz

Optionally verify the SLSA3 signatures generated using the OpenSSF’s slsa-framework/slsa-github-generator during the release process. To verify a release archive:

Mon, 01 Jan 0001 00:00:00 +0000

Migrating from kpt `v0.39` to `v1.0` #

Before you begin
What’s new and changed?
Migration steps
- For Package Publishers
  - Automated portion of migration
    - Changes made by the function
  - Manual portion of migration
- For Package Consumers
Timeline

kpt v1.0 is going to be the latest major release of the kpt CLI. The implementation of kpt v1.0 has changed considerably from kpt v0.39. A rich set of new features have been added as a result of the users’ input and requirements. Some features have been deprecated or refactored in ways that make them incompatible with kpt v0.39. Since these are backwards incompatible changes, there should be a way for users to migrate/fix their existing kpt packages which are compatible with v0.39 version of kpt, to become compatible with kpt v1.0. This document outlines the end to end migration journey of users using a comprehensive kpt package example.

Understanding 3-Way Merge in kpt

Mon, 01 Jan 0001 00:00:00 +0000

Overview #

When you run kpt pkg update, kpt needs to intelligently combine three versions of your package:

Original (origin): The upstream package version you initially fetched
Updated (upstream): The new upstream package version you’re updating to
Local (destination): Your local package with your customizations

kpt uses a 3-way merge algorithm to combine these versions, similar to how git merge works. This allows you to receive upstream improvements while preserving your local customizations.

Containerizing

Mon, 01 Jan 0001 00:00:00 +0000

KRM functions are distributed as container images. This guide covers building and running containerized functions.

Dockerfile #

The krm-functions-catalog provides a shared Dockerfile at build/docker/go/Dockerfile that all the catalog functions use. It accepts BUILDER_IMAGE and BASE_IMAGE as build args.

For standalone functions or local development, use a multi-stage build with a minimal base image. The function binary should be statically linked (no CGO), so it can run on scratch or distroless:

Interfaces

Mon, 01 Jan 0001 00:00:00 +0000

The SDK provides two interfaces for implementing KRM functions. Choose according to your function requirements.

The main functions below call fn.AsMain without fn.WithDocs to keep the interface examples focused. Production functions should embed documentation and pass fn.WithDocs(readme, metadata) — see the tutorial.

fn.Runner #

Use fn.Runner for transformers (mutators) and validators. This is the recommended interface for most functions.

type Runner interface {
 Run(context *Context, functionConfig *KubeObject, items KubeObjects, results *Results) bool
}

Characteristics:

Namespace provisioning using kpt CLI

Mon, 01 Jan 0001 00:00:00 +0000

What package are we creating ? #

Onboarding a new application or a micro-service is a very common task for a platform team. It involves provisioning a dedicated namespace (and other associated resources) where all resources that belong to the application reside. In this guide, we will create a package that will be used for provisioning a namespace.

Prerequisites #

Repositories #

Platform teams will have to setup two repos:

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

Testing

Mon, 01 Jan 0001 00:00:00 +0000

The SDK provides a golden test framework in fn/testhelpers for snapshot-based testing of KRM functions.

Golden Test Pattern #

Golden tests compare the function output against the expected baseline files. This approach catches regressions and makes it easy to review output changes.

Directory Structure #

testdata/
├── test-case-1/
│ ├── _expected.yaml # Expected output (full ResourceList YAML)
│ ├── _fnconfig.yaml # FunctionConfig for this test case
│ └── resources.yaml # Input KRM resources
└── test-case-2/
 ├── _expected.yaml
 ├── _fnconfig.yaml
 └── resources.yaml

Conventions:

The Rationale behind kpt

Mon, 01 Jan 0001 00:00:00 +0000

Most Kubernetes users either manage their resources using conventional imperative graphical user interfaces, command-line tools (kubectl), and automation (e.g., Operators) that operate directly against Kubernetes APIs, or declarative configuration tools, such as Helm, Terraform, cdk8s, or one of the dozens of other tools. At small scale, this is largely driven by preference and familiarity.

As companies expand the number of Kubernetes development and production clusters they use, creating and enforcing consistent configurations and security policies across a growing environment becomes difficult. At that point, the choice of management surface is no longer driven by preference, but by capabilities. To address this challenge, it is increasingly common for platform administrators to use “GitOps” methodology to deploy configuration consistently across clusters and environments with a version-controlled deployment process. Using the same principles as Kubernetes itself, GitOps reconciles the desired state of clusters with a set of Kubernetes declarative configuration files in a source control system, namely git.

Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial walks through the end-to-end workflow for building a KRM function using the Go SDK. By the end, you will have a working function with embedded documentation, golden tests, and support for --help, --doc, and standalone file mode.

For a complete working example, see go/get-started/.

1. Create Your Function #

A KRM function implements the fn.Runner interface:

type Runner interface {
 Run(context *Context, functionConfig *KubeObject, items KubeObjects, results *Results) bool
}

Here is a minimal function that sets labels on all the resources:

kpt Documentation on kpt documentation

FAQ #

What is the roadmap for kpt? #

How is kpt different from other solutions? #

Tenant onboarding #

Value propagation pattern #

String generation function #

Variant construction pattern #

Types of packages #

Installation #

Binaries #

Migrating from kpt v0.39 to v1.0 #

Understanding 3-Way Merge in kpt

Overview #

Containerizing

Dockerfile #

Interfaces

fn.Runner #

Namespace provisioning using kpt CLI

What package are we creating ? #

Prerequisites #

Repositories #

Search Results

Testing

Golden Test Pattern #

Directory Structure #

The Rationale behind kpt

Tutorial

1. Create Your Function #

Migrating from kpt `v0.39` to `v1.0` #