nyl 0.0.2

Default template for PDM package

nyl

Nyl is a versatile Kubernetes resource management tool that fulfills various functions to enable reusable deployment configurations.

Features

• Generate Kubernetes manifests from a simple YAML configuration with templating support.
• Inject secrets into Kubernetes manifests as time of generation.
• Bootstrap a cluster and transfer control to ArgoCD or use it to manage a cluster from CI/CD or locally.
• Connect to a Kubernetes cluster via an SSH tunnel.

Roadmap

• Integrate as an ArgoCD ConfigManagementPlugin.
• Diffing
• How to work around fields owned by a different field manager (e.g. MetalLB CRD conversion..caBundle) or Job resources?

Concepts

Packages

A package is similar to a Helm chart in that it is a source for Kubernetes resources that can make use of templating to conditionally render resources and inject values into them. Resources generated by packages may make use of Nyl-specific resource kinds that are only available time of resource generation (see the Templating > Resource Kinds section below).

Nyl packages can be checked into a source repository in a DRY form, but can be compiled to a bundle (e.g. including other referenced packages or Helm charts) for deployment when needed (e.g. for shipping to an air-gapped environment).

Packages may have a nyl-package.yaml file that defines a schema for the package parameters and additional metadata. A package without this file may still accept and use parameters in its templates.

Applications

An application is an instance of one package that is deployed to a Kubernetes cluster and are in turn defined also in a Nyl package. Packages instantiated as applications may not produce other applications. Applications are usually accompanied by a nyl-deployment.yaml file that defines the top-level templating context for the package(s), such as the secret store.

When deploying a package as an application, the package must not generated resources other than applications, as all deployed resources must be owned by an application.

Deployment

A deployment is where things get together: This is the place where you define the applications that should be deployed to a Kubernetes cluster, which cluster they are being deployed to, as well as sourcing secrets from a secret store. The configuration for a deployment is defined in a nyl-deployment.yaml file.

apiVersion: nyl/v1
kind: Deployment
spec:
  secretStores:
    default:
      type: Sops
      path: secrets.yaml

Spec

• secrets (array): The secret stores to make available in the templating context of the deployment. Any secrets need to be injected from these stores into the application values at templating time.

Templating

Nyl uses Jinja2 as a templating engine, and as such is slightly different from Helm.

Injecting secrets

Secrets are only available at the deployment level and need to be propagated further down.

apiVersion: nyl/v1
kind: Application
metadata:
  name: my-app
spec:
  package: ./path/to/package
  values:
    theSecret: {{ Secrets.default.get("my-secret") }}

Resource kinds

At templating time, Nyl supports special resource kinds that will be expanded to more Kubernetes resources.

templating.nyl/v1/HelmChart

This resource can be used to instantiate Helm charts as part of a package.

apiVersion: templating.nyl/v1
kind: HelmChart
spec:
  repository: https://kubernetes.github.io/ingress-nginx
  chart: ingress-nginx
  version: 4.10.1
  releaseName: ingress-nginx
  releaseNamespace: ingress-nginx
  values: {}

Spec

• repository (string): The Helm repository URL, OCI registry URL (sans the chart name), a local path or a Git repository clone URL.
• chart (string): The name of the chart in the repository, the chart name to append to the OCI registry URL, the name of the chart in the local path or the path to the chart in the Git repository.
• version (string): The version of the chart to use. Only relevant for Helm/OCI repositories.
• releaseName (string): The name of the Helm release.
• releaseNamespace (string): The namespace to install the Helm release into. If any resources generated by the chart have no metadata.namespace field, it will be set to this value.
• values (object): The values to pass to the Helm chart.

templating.nyl/v1/Package

Use this resource to instantiate another package.

apiVersion: templating.nyl/v1
kind: Package
spec:
  package: ./path/to/package
  values: {}

Spec

• package (string): The path to the package to instantiate. Must be prefixed with ./ to be resolved relative to the package that references it. Otherwise, it will be resolved in a search path that is defined in the nyl-deployment.yaml file.
• values (object): The values to pass to the package.