nyl 0.7.1__tar.gz → 0.7.2__tar.gz

nyl-0.7.2/.changelog/0.7.2.toml

@@ -0,0 +1,31 @@
+release-date = "2025-01-17"
+
+[[entries]]
+id = "00755f35-1e28-4946-9cbb-eccb2735b9fb"
+type = "feature"
+description = "Add `nyl add namespace` command"
+author = "@NiklasRosenstein"
+
+[[entries]]
+id = "1a17887c-ed8a-40a9-9ff5-11b594c20dd4"
+type = "docs"
+description = "Fix links in docs and add information on how to use the `HelmChart.spec.chart` field"
+author = "@NiklasRosenstein"
+
+[[entries]]
+id = "3f471926-8529-4e46-8d73-41c2825a3578"
+type = "feature"
+description = "Add `nyl add chart` command"
+author = "@NiklasRosenstein"
+
+[[entries]]
+id = "242fa8b1-225f-42f4-bf7f-fe6af806f0b5"
+type = "docs"
+description = "Add note to discurage from using `{{ .Release.Namespace }}` in Helm charts"
+author = "@NiklasRosenstein"
+
+[[entries]]
+id = "a09f0665-99a6-4a54-b0eb-afe4f719a320"
+type = "breaking change"
+description = "Rename annotation `nyl.io/default-namespace` to `nyl.io/is-default-namespace`"
+author = "@NiklasRosenstein"

{nyl-0.7.1 → nyl-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nyl
-Version: 0.7.1
+Version: 0.7.2
 Summary: Advanced templating engine for Kubernetes and GitOps.
 Author-email: Niklas Rosenstein <rosensteinniklas@gmail.com>
 License: MIT

{nyl-0.7.1 → nyl-0.7.2}/docs/content/changelog.md

@@ -1,6 +1,34 @@
 # Changelog
 
-## 0.7.0
+## 0.7.2 (2025-01-17)
+
+<table><tr><th>Type</th><th>Description</th><th>PR</th><th>Issues</th><th>Author</th></tr>
+  <tr><td>Feature</td><td>
+
+Add `nyl add namespace` command</td><td></td><td></td><td>@NiklasRosenstein</td></tr>
+  <tr><td>Docs</td><td>
+
+Fix links in docs and add information on how to use the `HelmChart.spec.chart` field</td><td></td><td></td><td>@NiklasRosenstein</td></tr>
+  <tr><td>Feature</td><td>
+
+Add `nyl add chart` command</td><td></td><td></td><td>@NiklasRosenstein</td></tr>
+  <tr><td>Docs</td><td>
+
+Add note to discurage from using `{{ .Release.Namespace }}` in Helm charts</td><td></td><td></td><td>@NiklasRosenstein</td></tr>
+  <tr><td>Breaking change</td><td>
+
+Rename annotation `nyl.io/default-namespace` to `nyl.io/is-default-namespace`</td><td></td><td></td><td>@NiklasRosenstein</td></tr>
+</table>
+
+## 0.7.1 (2025-01-17)
+
+<table><tr><th>Type</th><th>Description</th><th>PR</th><th>Issues</th><th>Author</th></tr>
+  <tr><td>Fix</td><td>
+
+Fixed a bug where pulling two different charts with the same version number from the same repository conflated the cache key and ended up with Nyl using the wrong chart (that which has been pulled first).</td><td></td><td></td><td>@NiklasRosenstein</td></tr>
+</table>
+
+## 0.7.0 (2025-01-17)
 
 <table><tr><th>Type</th><th>Description</th><th>PR</th><th>Issues</th><th>Author</th></tr>
   <tr><td>Breaking change</td><td>

{nyl-0.7.1 → nyl-0.7.2}/docs/content/reference/templating/components.md

@@ -8,7 +8,7 @@ Nyl components are effectively templates that you can instantiate them similar t
 are treated in a way similar to CRDs, only that they will never to pushed to the Kubernetes API server and instead be
 replaced throuhg a first reconcilation phase during `nyl template`.
 
-Components are built on top of Helm chart [inlining](./inlining.md#helm-charts).
+Components are built on top of Helm chart [inlining](./inlining/helmcharts.md).
 
 ## How Nyl looks for components
 

{nyl-0.7.1 → nyl-0.7.2}/docs/content/reference/templating/inlining/helmcharts.md

@@ -5,12 +5,12 @@ weight: 5
 # HelmChart
 
 Nyl allows you to inline Helm charts by specifying a `HelmChart` resource in your manifest. Just like any other
-resource, the Helm chart resource values can be templated using Nyl's [structured templating](../templating/basics.md)
+resource, the Helm chart resource values can be templated using Nyl's [structured templating](../basics.md)
 (for example to inject secrets), and are then rendered to Kubernetes resources that are inlined in your configuration.
 
 __Example__
 
-```yaml 
+```yaml
 apiVersion: inline.nyl.io/v1
 kind: HelmChart
 metadata:
@@ -27,6 +27,79 @@ spec:
         type: LoadBalancer
 ```
 
+When writing Helm charts, we discourage from using `namespace: {{ .Release.Namespace }}`. This is because when you
+instantiate a `HelmChart` in Nyl without specifying a `.metadata.namespace`, the Helm chart will be templated without
+the `--namespace` option. This will have Helm assume `.Release.Namespace == "default"`, thus all `namespace` fields
+in the generated resource will be set to `default`. This is not what you want, as it will prevent Nyl from injecting the
+appropriate namespace based on the context of your local manifest file.
+
+If you are dealing with a Helm chart that does use `namespace: {{ .Release.Namespace }}`, be sure to set the `.metadata.namespace` field of your Nyl `HelmChart` resource.
+
+## ChartRef
+
+The `.spec.chart` field defines the source of the Helm chart. You can source charts from a Helm HTTP(S) or OCI repository, a Git repository or a local directory. Local chart paths are first resolved in the Nyl search path that can be defined in the [Project settings](../../configuration/projects.md).
+
+!!! note
+    We highly recommend to add a as a comment the link to <artifacthub.io>, if available. This allows you to easily
+    look up the chart version, values and documentation.
+
+=== "HTTP(S) repository"
+
+    ```yaml
+    # ...
+    spec:
+      chart:
+        # https://artifacthub.io/packages/helm/bitnami/nginx
+        repository: https://charts.bitnami.com/bitnami
+        name: nginx
+        version: 18.3.5 # 1.27.3
+    ```
+
+=== "OCI repository"
+
+    ```yaml
+    # ...
+    spec:
+      chart:
+        # https://artifacthub.io/packages/helm/bitnami/nginx
+        repository: oci://registry-1.docker.io/bitnamicharts
+        name: nginx
+        version: 18.3.5 # 1.27.3
+    ```
+
+    Note how the OCI URL does not contain the chart name. It is specified separately in the `name` field.
+
+=== "Git repository"
+
+    ```yaml
+    # ...
+    spec:
+      chart:
+        # This can be any valid URL that can be used with `git clone`, plus an optional URL query parameter that is
+        # either `ref` (for a Git reF) or `rev` (or a Git commit SHA).
+        git: https://github.com/bitnami/charts?rev=e808ba0
+
+        # If the chart is not located at the root of the repository, point to its subdirectory.
+        path: bitnami/nginx
+    ```
+
+=== "Local directory"
+
+    ```yaml
+    # ...
+    spec:
+      chart:
+        # Explicitly relative paths (e.g. starting with `./`) are resolved relative to the manifest source file that
+        # defines the `HelmChart` resource.
+        path: ./charts/nginx
+
+        # Absolute paths are resolved absolute in the local filesystem. This is not usually useful except for testing.
+        path: /path/to/chart
+
+        # Any other path is resolved in the Nyl project search path.
+        path: nginx
+    ```
+
 ### Comparison to native ArgoCD Helm applications
 
 Nyl may look similar to Helm in the sense that it allows for templating YAML files. However, there are some important

{nyl-0.7.1 → nyl-0.7.2}/docs/content/reference/templating/inlining/overview.md

@@ -6,5 +6,5 @@ title: Overview
 
 Nyl supports inlining of Kubernetes resources generated from templates in your configuration. Resources that are
 inlined by Nyl are typically in the `inline.nyl.io/v1` API group, however Nyl also has the concept of
-[components](./components.md) which effectively allow you to define your own API groups and resource kinds for
+[components](../components.md) which effectively allow you to define your own API groups and resource kinds for
 inlined resources.

{nyl-0.7.1 → nyl-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nyl"
-version = "0.7.1"
+version = "0.7.2"
 description = "Advanced templating engine for Kubernetes and GitOps."
 authors = [
     {name = "Niklas Rosenstein", email = "rosensteinniklas@gmail.com"},

{nyl-0.7.1 → nyl-0.7.2}/src/nyl/commands/__init__.py

@@ -121,6 +121,7 @@ def version() -> None:
     sys.exit(0)
 
 
+from . import add  # noqa: E402
 from . import argocd  # noqa: E402
 from . import crds  # noqa: F401,E402
 from . import new  # noqa: E402
@@ -131,6 +132,7 @@ from . import template  # noqa: F401,E402
 from . import tools  # noqa: E402
 from . import tun  # noqa: E402
 
+app.add_typer(add.app)
 app.add_typer(argocd.app)
 app.add_typer(new.app)
 app.add_typer(profile.app)

nyl-0.7.2/src/nyl/commands/add.py

@@ -0,0 +1,118 @@
+"""
+Convenient CLI for making ammends to Kubernetes manifest files.
+"""
+
+from pathlib import Path
+import sys
+from typing import Any
+from typer import Argument, Option, Typer
+from loguru import logger
+import yaml
+
+from nyl.commands.template import (
+    DEFAULT_NAMESPACE_ANNOTATION,
+    ManifestsWithSource,
+    is_namespace_resource,
+    load_manifests,
+)
+from nyl.resources import ObjectMetadata
+from nyl.resources.helmchart import ChartRef, HelmChart, HelmChartSpec
+from nyl.tools.typer import new_typer
+from nyl.tools.types import Manifests
+
+app: Typer = new_typer(name="add", help=__doc__)
+
+MANIFEST_OPTION = Option(..., "-m", "--manifest", help="The manifest YAML file to add the namespace to.")
+
+
+@app.command()
+def namespace(
+    manifest: Path = MANIFEST_OPTION,
+    name: str = Argument(help="Name of the namespace to add."),
+) -> None:
+    """
+    Add a Kubernetes `Namespace` resource definition to the top of the specified manifest file.
+
+    If this is the first namespace defined in the manifest, it will be annotated with `nyl.io/is-default-namespace`.
+    """
+
+    if manifest.exists():
+        content = manifest.read_text()
+        resources = load_manifests([manifest])[0]
+    else:
+        content = ""
+        resources = ManifestsWithSource(Manifests([]), manifest)
+
+    if any(is_namespace_resource(x) and x["metadata"]["name"] == name for x in resources.manifests):
+        logger.error("Namespace '{}' already exists in {}.", name, manifest)
+        sys.exit(1)
+
+    namespace: dict[str, Any] = {
+        "apiVersion": "v1",
+        "kind": "Namespace",
+        "metadata": {
+            "name": name,
+        },
+    }
+
+    as_default = not any(is_namespace_resource(x) for x in resources.manifests)
+    if as_default:
+        namespace["metadata"]["annotations"] = {DEFAULT_NAMESPACE_ANNOTATION: "true"}
+
+    if not content.lstrip().startswith("---"):
+        content = f"---\n{content}"
+    content = f"---\n{yaml.safe_dump(namespace, sort_keys=False)}\n{content}"
+    manifest.write_text(content)
+
+    logger.info("Added {}namespace '{}' to {}.", "default " if as_default else "", name, manifest)
+
+
+@app.command()
+def chart(
+    manifest: Path = MANIFEST_OPTION,
+    name: str = Argument(help="The release name."),
+    namespace: str | None = Option(None, "-n", "--namespace", help="The release namespace."),
+    repository: str | None = Option(None, "--repo", "--repository", help="The chart repository."),
+    chart: str | None = Option(None, "--chart", help="The chart name."),
+    version: str | None = Option(None, "--version", help="The chart version."),
+    path: str | None = Option(None, "--path", help="The chart path if consumed from disk."),
+    git: str | None = Option(None, "--git", help="Git URL of the chart."),
+) -> None:
+    """
+    Append a Nyl `HelmChart` resource to the specified manifest file.
+    """
+
+    if repository or chart or version:
+        if not repository or not chart or not version:
+            logger.error("If any of --repo, --chart, or --version are specified, all must be specified.")
+            sys.exit(1)
+
+        if path or git:
+            logger.error("If --repo is specified, --path and --git must not be specified.")
+            sys.exit(1)
+
+    if git:
+        if repository:
+            logger.error("If --git is specified, --repo must not be specified.")
+            sys.exit(1)
+
+    resource = HelmChart(
+        metadata=ObjectMetadata(name=name, namespace=namespace),
+        spec=HelmChartSpec(
+            chart=ChartRef(
+                path=path,
+                git=git,
+                repository=repository,
+                name=chart,
+                version=version,
+            ),
+            values={},
+        ),
+    )
+
+    content = manifest.read_text() if manifest.exists() else ""
+    if not content.rstrip().endswith("---"):
+        content += "\n---\n"
+    content += yaml.safe_dump(resource.dump())
+
+    manifest.write_text(content)

{nyl-0.7.1 → nyl-0.7.2}/src/nyl/commands/template.py

@@ -29,7 +29,7 @@ from nyl.tools.logging import lazy_str
 from nyl.tools.types import Manifest, Manifests
 
 DEFAULT_PROFILE = "default"
-DEFAULT_NAMESPACE_ANNOTATION = "nyl.io/default-namespace"
+DEFAULT_NAMESPACE_ANNOTATION = "nyl.io/is-default-namespace"
 
 
 # Need an enum for typer
@@ -431,7 +431,7 @@ def get_default_namespace_for_manifest(source: ManifestsWithSource, fallback: st
     fallback.
 
     - If there are multiple `v1/Namespace` resources declared in the manifest, we pick the one with the
-    `nyl.io/default-namespace` label. If there is no such namespace, a warning is logged and we pick the first one
+    `nyl.io/is-default-namespace` label. If there is no such namespace, a warning is logged and we pick the first one
     alphabetically.
 
     Returns:

{nyl-0.7.1 → nyl-0.7.2}/src/nyl/resources/__init__.py

@@ -6,6 +6,7 @@ from abc import ABC
 from dataclasses import dataclass
 from typing import ClassVar, Collection, cast
 
+from databind.core import SerializeDefaults
 from databind.json import dump as ser
 from databind.json import load as deser
 from typing_extensions import Self
@@ -107,7 +108,7 @@ class NylResource(ABC):
         Dump the resource to a manifest.
         """
 
-        manifest = cast(Manifest, ser(self, type(self)))
+        manifest = cast(Manifest, ser(self, type(self), settings=[SerializeDefaults(False)]))
         manifest["apiVersion"] = self.API_VERSION
         manifest["kind"] = self.KIND
         return Manifest(manifest)

{nyl-0.7.1 → nyl-0.7.2}/uv.lock

@@ -384,7 +384,7 @@ wheels = [
 
 [[package]]
 name = "nyl"
-version = "0.7.0"
+version = "0.7.1"
 source = { editable = "." }
 dependencies = [
     { name = "bcrypt" },