Framework Guides

Migrate from catalog modules to platform feature modules

TL;DR:

• The Kubestack catalog is deprecated, existing catalog pages remain available for reference
• Platform features are now provisioned from upstream sources using a generated Terraform module
• Your AI coding agent scaffolds and maintains the module as part of your repository
• Existing environment configuration carries over, because both approaches use the same kustomization overlay attributes

The catalog is deprecated

The Kubestack catalog is deprecated. Kubestack will not publish new catalog module versions, and the catalog should not be used for new platform features. Existing catalog pages remain available for reference.

The new default is the platform feature approach documented in the Kubestack skill: your AI coding agent scaffolds a small Terraform module in your repository that deploys the upstream source of the feature you want, rendered from a Helm chart or a plain YAML manifest. This guide explains the approach and how to migrate existing catalog modules to it.

Learn the Kubestack skill at https://www.kubestack.com/SKILL.md

Why the approach changed

Catalog modules bundle upstream manifests into packaged Terraform modules, versioned with a -kbst.x suffix. Using them means waiting for the packaging to catch up with every upstream release, and configuring the feature through an indirection.

The generated module approach removes the indirection:

• The upstream source is rendered into manifests/upstream.yaml by helm template, using a committed values.yaml
• The rendered manifests and the module live in your repository, you own them like the rest of your platform
• Updates come directly from the upstream project, there is no repackaging step
• Your agent can scaffold, update and remove the feature without any external dependency

What does not change: the module uses the same kustomization overlay module type and the same configuration inheritance as the catalog modules. Your per-environment patches carry over almost one to one.

The platform feature module

A platform feature is a local Terraform module in your repository:

.
├── modules/
│   └── <feature_name>/
│       ├── README.md                  # upstream source, version, regeneration command
│       ├── values.yaml                # Helm values, configured for the base environment
│       ├── manifests/
│       │   └── upstream.yaml          # rendered by helm template, never edited directly
│       ├── versions.tf
│       └── main.tf                    # kustomization overlay module + configuration map
└── <cluster_name>_feature_<feature_name>.tf   # cluster binding, one per cluster

The module files are straightforward:

modules/<feature_name>/versions.tf

terraform {
  required_providers {
    kustomization = {
      source = "kbst/kustomization"
    }
  }
}

modules/<feature_name>/main.tf

module "<feature_name>" {
  providers = {
    kustomization = kustomization
  }

  source = "github.com/kbst/terraform-kubestack//kustomization/overlay?ref=<framework version>"

  configuration = {
    apps = {
      resources = [
        "${path.module}/manifests/upstream.yaml",
      ]
    }

    ops = {}
  }
}

Use the same framework version in ?ref= as all other modules in your repository.

<cluster_name>_feature_<feature_name>.tf

module "<cluster_name>_feature_<feature_name>" {
  providers = {
    kustomization = kustomization.<cluster_name>
  }

  source = "./modules/<feature_name>"
}

Each cluster the feature is deployed to gets its own binding file with its cluster's kustomization provider alias.

Rendering upstream with helm template

The only step the agent cannot do for you is running helm template, because the rendered upstream.yaml is generated from the upstream chart. The agent provides the exact command and asks you to run it.

For a chart distributed via OCI, for example cert-manager:

helm template cert-manager oci://quay.io/jetstack/cert-manager \
  --version <chart-version> \
  --values modules/cert_manager/values.yaml \
  --namespace cert-manager \
  --create-namespace \
  --include-crds \
  > modules/cert_manager/manifests/upstream.yaml

For a chart from a traditional Helm repository:

helm repo add <repo-name> <repo-url>

helm template <release-name> <repo-name>/<chart-name> \
  --version <chart-version> \
  --values modules/<feature_name>/values.yaml \
  --namespace <namespace> \
  --create-namespace \
  --include-crds \
  > modules/<feature_name>/manifests/upstream.yaml

--include-crds and --create-namespace ensure the namespace, CRDs and all resources end up in the single upstream.yaml. The kustomization provider handles creation order automatically.

The exact command, the chart source and the version are recorded in modules/<feature_name>/README.md. Never edit upstream.yaml directly, change values.yaml and re-run the command instead.

Upstream features that publish plain YAML manifests instead of a Helm chart follow the same structure, with the manifest fetched into manifests/upstream.yaml instead of being rendered.

Migrating an existing catalog module

Migrating a catalog module comes down to replacing the registry module block with the local module and its binding files. Using the Nginx catalog module on an EKS cluster as an example, your repository today contains a block like this:

module "eks_gc0_eu-west-1_service_nginx" {
  providers = {
    kustomization = kustomization.eks_gc0_eu-west-1
  }

  source  = "kbst.xyz/catalog/nginx/kustomization"
  version = "1.3.1-kbst.1"

  configuration = {
    apps = {}
    ops = {}
  }
}

Ask your agent to migrate it:

Migrate the nginx catalog module to a platform feature module

Your agent scaffolds modules/nginx/ and the binding files, then asks you to run the helm template command to render upstream.yaml.

eks_gc0_eu-west-1_feature_nginx.tf replaces the catalog module block:

module "eks_gc0_eu-west-1_feature_nginx" {
  providers = {
    kustomization = kustomization.eks_gc0_eu-west-1
  }

  source = "./modules/nginx"
}

Repeat for every cluster the catalog module is deployed to, then delete the old *_service_nginx.tf catalog module blocks.

Follow the GitOps workflow for the migration like for any other change: commit the new module, bindings and the rendered upstream.yaml on a feature branch and review the Terraform plan. If you are migrating multiple catalog modules, migrate them one by one, one pull request each, so the plans stay reviewable and a single breaking change is easy to isolate.

Updating platform features going forward

With the catalog gone, updates come directly from the upstream project. Instead of waiting for a new -kbst.x module version, you re-render upstream.yaml yourself.

Every feature module records its upstream source, version and the exact regeneration command in modules/<feature_name>/README.md. To update, your agent reads the README, provides the command with the new version for you to run, and reviews the diff with you for breaking changes.

Update the nginx platform feature to the latest version

Because upstream.yaml is a committed, generated file, the update is fully visible in the pull request diff. Reviewers see exactly what changed between the two upstream versions, and the GitOps pipeline validates the change against the internal environment before it is promoted.

Next steps

With your catalog modules migrated, adding new platform features works the same way. Ask your agent, e.g. Add the cert-manager platform feature to all clusters, and follow the recommendation it presents.

The full reference for the platform feature approach is part of the Kubestack skill.