k8s-libsonnet

repository·main·Indexed 42 days ago

https://github.com/jsonnet-libs/k8s-libsonnet

A Jsonnet library providing Kubernetes artifacts generated from the official OpenAPI specification. It serves as a high-performance replacement for ksonnet-gen and kube-jsonnet/k, offering structured abstractions for Kubernetes API groups across versions v1.33, v1.34, v1.35, and v1.36. The library is designed for use with Grafana Tanka and can be installed via jsonnet-bundler (jb).

Tokens
161K
Snippets
676
Records
906
Agent score
52%

What's inside k8s-libsonnet

  1. Configure MutatingWebhook in admissionregistration.v1

    main

    Use the admissionregistration.v1.mutatingWebhook library to describe an admission webhook and the resources/operations it applies to. This library provides a set of with* functions to build a MutatingWebhookConfiguration object.

    Key configuration areas include:

    • Identity: Set the webhook name using withName(name).
    • Rules: Define which operations and resources trigger the webhook using withRules(rules) or withRulesMixin(rules).
    • Matching: Use withMatchPolicy(matchPolicy) to choose between Exact or Equivalent matching, and withMatchConditions(matchConditions) for fine-grained filtering.
    • Failure Handling: Control behavior when the webhook fails using withFailurePolicy(failurePolicy) (values: Ignore or Fail).
    • Lifecycle: Specify if the webhook should be re-invoked using withReinvocationPolicy(reinvocationPolicy) (Never or IfNeeded).
  2. Configure MutatingWebhook for Kubernetes 1.33

    main

    The admissionregistration.v1.mutatingWebhook module is used to describe a mutating admission webhook and the specific Kubernetes resources and operations it should intercept. This module provides a functional API (using with* patterns) to construct a MutatingWebhookConfiguration object.

    Key configuration areas include:

    • Identity: Set the webhook's name using withName(name).
    • Routing: Define where the API server sends requests using clientConfig (via withUrl or withService).
    • Filtering: Use withRules, withNamespaceSelector, or withObjectSelector to limit which requests trigger the webhook.
    • Behavior: Control error handling with withFailurePolicy, timeouts with withTimeoutSeconds, and re-invocation logic with withReinvocationPolicy.
  3. What is a CertificateSigningRequest (CSR)

    main

    A CertificateSigningRequest (CSR) object is a mechanism used to obtain x509 certificates. The process involves submitting a certificate signing request, which is then asynchronously approved and issued.

    Common use cases include:

    1. Kubelet Client Authentication: Kubelets use the kubernetes.io/kube-apiserver-client-kubelet signerName to obtain client certificates for authenticating to the kube-apiserver.
    2. Kubelet Serving TLS: Kubelets use the kubernetes.io/kubelet-serving signerName to obtain serving certificates for TLS endpoints.
    3. General Authentication: Requesting client certificates via the kubernetes.io/kube-apiserver-client signerName.
    4. Custom Signers: Obtaining certificates from non-Kubernetes signers.
  4. What is a CSINode object?

    main

    A CSINode object holds information about all Container Storage Interface (CSI) drivers installed on a specific node.

    Key characteristics:

    • Automatic Population: CSI drivers do not typically create these objects directly. Instead, if they use the node-driver-registrar sidecar container, the kubelet automatically populates the CSINode object during plugin registration.
    • Naming: The CSINode object shares the same name as the Kubernetes Node it describes.
    • Ownership: It contains an OwnerReference pointing to the corresponding Node object.
    • Presence: If the object is missing, it implies either no CSI drivers are available on that node or the kubelet version is too old to support this object.
  5. How label selectors work in ClusterTrustBundle

    main

    When using labelSelector to find ClusterTrustBundle objects, the requirements provided via withMatchLabels and withMatchExpressions are ANDed together.

    • matchLabels: A map of {key, value} pairs. Each pair is treated as an equality requirement (key In [value]).
    • matchExpressions: A list of requirements that are all required to be met.
    • Empty vs Null: An empty label selector matches all objects, while a null label selector matches no objects.
  6. How matchConditions work in ValidatingWebhooks

    main

    Match conditions are a list of requirements that must be met for a request to be sent to the webhook. They act as a secondary filter after rules, namespaceSelector, and objectSelector have matched.

    Logic Flow:

    1. Filtering: If ANY matchCondition evaluates to FALSE, the webhook is skipped.
    2. Execution: If ALL matchConditions evaluate to TRUE, the webhook is called.
    3. Error Handling: If a condition results in an error (and none are FALSE):
      • If failurePolicy=Fail, the request is rejected.
      • If failurePolicy=Ignore, the error is ignored and the webhook is skipped.

    There is a maximum limit of 64 match conditions.

  7. Configure webhook matching logic with matchPolicy

    main

    The withMatchPolicy(matchPolicy) function defines how the rules list is used to match incoming requests.

    • Exact: Matches a request only if it exactly matches a specified rule. If a resource can be accessed via multiple API versions (e.g., apps/v1 and apps/v1beta1) but your rule only specifies apps/v1, requests via v1beta1 will not trigger the webhook.
    • Equivalent (Default): Matches a request if it modifies a resource listed in the rules, even via a different API group or version. For example, a request to apps/v1beta1 would be converted to apps/v1 and sent to the webhook if the rule specifies apps/v1.
  8. Migrating from ksonnet-lib to k8s-libsonnet

    main

    While k8s-libsonnet can replace ksonnet-lib, be aware of the following incompatibilities:

    • Type Objects vs First-Class Citizens: ksonnet-lib often exposes types as hidden objects inside others (e.g., core.v1.container.envType). In k8s-libsonnet, these are first-class citizens (e.g., core.v1.envVar).
    • Mandatory Name Arguments: The new(name) constructors in this library require a mandatory name argument, which was not always required in ksonnet-lib.
    • Function Chaining: This library does not support function chaining (e.g., container.new(name).withEnv(env)) due to Jsonnet compiler performance penalties. Instead, use the mixin pattern: container.new(name) + container.withEnv(env).

    If you need to support both libraries during a transition, use the ksonnet-util library to bridge these differences.

  9. Understand RawExtension for vendor-specific parameters

    main

    When working with v1alpha3.OpaqueDeviceConfiguration, parameters are handled via RawExtension. This allows the API to store raw JSON/YAML that is later unpacked into specific plugin types during conversion.

    To implement this pattern in your own Go-based API extensions:

    1. In your external versioned struct, use runtime.RawExtension for the field.
    2. In your internal struct, use runtime.Object for the same field.
    3. Register your plugin types in the DefaultScheme so the conversion process can unpack the RawExtension into the correct object type.
    // Internal package:
    type MyAPIObject struct {
    	runtime.TypeMeta `json:",inline"`
    	MyPlugin runtime.Object `json:"myPlugin"`
    }
    
    type PluginA struct {
    	AOption string `json:"aOption"`
    }
    
    // External package:
    type MyAPIObject struct {
    	runtime.TypeMeta `json:",inline"`
    	MyPlugin runtime.RawExtension `json:"myPlugin"`
    }
    
    type PluginA struct {
    	AOption string `json:"aOption"`
    }
    
    // On the wire, the JSON will look something like this:
    {
    	"kind":"MyAPIObject",
    	"apiVersion":"v1",
    	"myPlugin": {
    		"kind":"PluginA",
    		"aOption":"foo",
    	},
    }
  10. Configure DeviceSubRequest in Kubernetes v1.33

    main

    A DeviceSubRequest describes a request for a device provided in the claim.spec.devices.requests[].firstAvailable array. It is used to request a single resource or several identical devices.

    Note that DeviceSubRequest is similar to a top-level Request, but it does not expose AdminAccess or FirstAvailable fields, as those are reserved for top-level requests. Recursive FirstAvailable fields are not supported.

  11. Configure Ephemeral Volume via volumeClaimTemplate

    main

    In Kubernetes v1.36, an ephemeralVolumeSource can represent an ephemeral volume handled by a normal storage driver using a volumeClaimTemplate.

    This template is used to produce PersistentVolumeClaim objects as part of the ephemeral volume lifecycle. The volumeClaimTemplate object contains metadata and spec fields to define the requirements for the generated claim.

    core.v1.volumeClaimTemplate { ... }