Metadata-Version: 2.1
Name: nyl
Version: 0.0.2
Summary: Default template for PDM package
Author-Email: Niklas Rosenstein <rosensteinniklas@gmail.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: databind>=4.5.2
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: jinja2>=3.1.4
Requires-Dist: loguru>=0.7.2
Requires-Dist: kubernetes>=30.1.0
Requires-Dist: typer>=0.12.3
Requires-Dist: filelock>=3.15.4
Requires-Dist: stablehash>=0.2.0
Requires-Dist: nr-stream>=1.1.5
Requires-Dist: requests>=2.32.3
Description-Content-Type: text/markdown

# 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](#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.

```yaml
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

  [Jinja2]: https://jinja.palletsprojects.com/en/3.0.x/

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.

```yaml
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.

```yaml
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.

```yaml
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.
