mirror of
https://github.com/yannh/kubeconform.git
synced 2026-02-19 01:47:02 +00:00
77 lines
3.7 KiB
Go
77 lines
3.7 KiB
Go
// Copyright 2022 Google LLC
|
||
//
|
||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
// you may not use this file except in compliance with the License.
|
||
// You may obtain a copy of the License at
|
||
//
|
||
// http://www.apache.org/licenses/LICENSE-2.0
|
||
//
|
||
// Unless required by applicable law or agreed to in writing, software
|
||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
// See the License for the specific language governing permissions and
|
||
// limitations under the License.
|
||
|
||
/*
|
||
Package fn provides the SDK to write KRM functions.
|
||
|
||
# Before you start
|
||
|
||
This fn SDK requires some basic KRM function Specification knowledge. To make the best usage of your time, we recommend
|
||
you to be familiar with "ResourceList" before moving forward.
|
||
|
||
The KRM Function Specification, or "ResourceList", defines the standards of the inter-process communication between
|
||
the orchestrator (i.e. kpt CLI) and functions.
|
||
|
||
See KRM Function Specification reference in https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md
|
||
|
||
# KRM Function
|
||
|
||
A KRM function can mutate and/or validate Kubernetes resources in a ResourceList.
|
||
|
||
The ResourceList type and the KubeObject type are the core parts of this package.
|
||
The ResourceList type maps to the ResourceList in the function spec.
|
||
|
||
Read more about how to use KRM functions in https://kpt.dev/book/04-using-functions/
|
||
|
||
Read more about how to develop a KRM function in https://kpt.dev/book/05-developing-functions/
|
||
|
||
A general workflow is:
|
||
1. Reads the "ResourceList" object from STDIN.
|
||
2. Gets the function configs from the "ResourceList.FunctionConfig".
|
||
3. Mutate or validate the Kubernetes YAML resources from the "ResourceList.Items" field with the function configs.
|
||
4. Writes the modified "ResourceList" to STDOUT.
|
||
5. Write function message to "ResourceList.Results" with severity "Info", "Warning" or "Error"
|
||
|
||
# KubeObject
|
||
|
||
The KubeObject is the basic unit to perform operations on KRM resources.
|
||
|
||
In the "AsMain", both "Items" and "FunctionConfig"
|
||
are converted to the KubeObject(s).
|
||
|
||
If you are familiar with unstructured.Unstructured, using KubeObject is as simple as using unstructured.Unstructured.
|
||
You can call function like `NestedStringOrDie` `SetNestedStringMap`, etc.
|
||
|
||
Except that KubeObject will not have pass-in interface arguments, nor will return an interface.
|
||
Instead, you shall treat each KubeObject field (slice, or non-string map）as SubObject.
|
||
|
||
SubObject also have most of the KubeObject methods, except the MetaType or NameType specific methods like "GetNamespace", "SetLabel".
|
||
This is because SubObject is designed as a sub object of KubeObject. SubObject to KubeObject is like `spec` section to `Deployment`.
|
||
You can get the Deployment name from `metadata.name`, KubeObject.GetName() or KubeObject.NestedString("metadata", "name").
|
||
But you cannot get "metadata.name" from a Deployment "spec". For "spec" SubObject, you can get the ".replicas" field by
|
||
SubObject.NestedInt64("replicas")
|
||
|
||
Besides unstructured style, another way to use KubeObject is to purely work on the KubeObject/SubObject by calling
|
||
"GetMap", "GetSlice", "UpsertMap" which expects the return to be SubObject(s) pointer.
|
||
|
||
# AsMain
|
||
|
||
"AsMain" is the main entrypoint. In most cases, you only need to provide the mutator or validation logic and have AsMain
|
||
handles the ResourceList parsing, KRM resource field type detection, read from STDIN and write to STDOUT.
|
||
|
||
"AsMain" accepts a struct that either implement the ResourceListProcessor interface or Runner interface.
|
||
|
||
See github.com/GoogleContainerTools/kpt-functions-sdk/go/fn/examples for detailed usage.
|
||
*/
|
||
package fn
|