Skip to main content
Version: Next 🚧

Install and Upgrade

krateoctl install plan and krateoctl install apply cover the main install and upgrade workflows for Krateo.

  • plan previews what krateoctl would do, without talking to the cluster.
  • apply executes the workflow against the cluster.
warning

Secrets must be managed separately. krateoctl does not bootstrap production secrets. Use Vault or create the required Kubernetes Secrets manually before running install or upgrade commands. See the Secrets Spec for the required names, keys, and namespace rules.

Table Of Contents​

When To Use Them​

Use these commands when you want to:

  • install Krateo from a local krateo.yaml
  • upgrade to a tagged release version
  • compare the computed plan with the last stored installation snapshot
  • run type-specific workflows for nodeport, loadbalancer, or ingress

Release Source​

When you pass --version, krateoctl switches to remote mode and fetches files from the releases repository instead of the local filesystem.

The default repository is:

This repository is used as a versioned source of installation assets. krateoctl builds raw GitHub URLs from it and looks for files such as:

  • krateo.yaml
  • krateo.<type>.yaml (e.g., krateo.nodeport.yaml)
  • krateo-overrides.yaml
  • krateo-overrides.<profile>.yaml
  • pre-upgrade.yaml
  • pre-upgrade.<type>.yaml
  • post-upgrade.yaml
  • post-upgrade.<type>.yaml

If you maintain your own release repository, you can point --repository at a GitHub repo with the same layout.

Profile Resolution​

When you specify --profile (e.g., --profile dev or --profile dev,aws-lb-hostname):

  • In remote mode (--version set): krateoctl searches for krateo-overrides.<profile>.yaml in the remote repository first, then falls back to local files if not found.
  • In local mode (no --version): krateoctl searches for krateo-overrides.<profile>.yaml in local files only.
  • If the profile is not found in either location (or both), krateoctl returns an error and stops execution.

This allows profiles to be overridden locally even when using a remote release, but requires at least one source to contain the profile file.

warning

Profiles persist across upgrades — Changing replaces values, omitting reverts to defaults. Always include your profiles in both plan and apply. Use plan --diff-installed before apply to verify changes.

Profiles​

Profiles allow you to customize a Krateo installation or upgrade without editing the base krateo.yaml. Each profile is a YAML file named krateo-overrides.<name>.yaml that krateoctl applies as a deep-merge overlay over the base configuration.

Profile naming and discovery​

krateoctl discovers profile files by convention:

  • Create a file named krateo-overrides.<profile-name>.yaml (e.g., krateo-overrides.my-custom.yaml)
  • Pass --profile <profile-name> to plan or apply (e.g., --profile my-custom)
  • krateoctl looks for krateo-overrides.my-custom.yaml — first in the remote releases repository (if --version is set), then on the local filesystem

Multiple profiles can be combined with a comma:

krateoctl install apply --version 3.0.0 --profile openshift,lb-hostname,my-custom

The merge order is: base config → krateo-overrides.yaml (if present) → each profile in left-to-right order. Later profiles override earlier ones on conflicting keys.

Built-in profiles​

The official krateoplatformops/releases repository ships these ready-to-use profiles:

ProfileFilePurpose
openshiftkrateo-overrides.openshift.yamlOpenShift-compatible security defaults for FinOps (CrateDB) and CNPG — disables runAsUser/runAsGroup, sets seccompProfile and drops all capabilities
lb-hostnamekrateo-overrides.lb-hostname.yamlAWS LoadBalancer hostname extraction (uses .hostname instead of .ip for LoadBalancer ingress selectors)
monitoringkrateo-overrides.monitoring.yamlEnables OpenTelemetry tracing on core-provider, deviser, resources-stack and events-stack
no-cnpgkrateo-overrides.no-cnpg.yamlDisables the CNPG component entirely (use with Bring-Your-Own-PostgreSQL)
no-finopskrateo-overrides.no-finops.yamlDisables the FinOps component entirely
debugkrateo-overrides.debug.yamlEnables debug environment variables on all components

Inspect any built-in profile directly:

https://github.com/krateoplatformops/releases/blob/main/krateo-overrides.<profile>.yaml

Profile structure and logic​

A profile file mirrors a subset of the krateo.yaml structure. There are two levels of customization, from higher-level to finer-grained:

What values can you override?​

The values block in a profile maps directly to the Helm chart values that krateoctl passes to each chart during installation. These values are defined in the krateo.yaml (or krateo.<type>.yaml) file under each step's with.values section.

For example, in krateo.nodeport.yaml the install-authn step defines:

steps:
  - id: install-authn
    type: chart
    with:
      repo: authn
      releaseName: authn
      url: https://charts.krateo.io
      version: 0.22.2
      values:
        image:
          repository: ghcr.io/krateoplatformops/authn
        service:
          type: NodePort
          nodePort: 30082
        env:
          AUTHN_KUBECONFIG_SERVER_URL: null

A profile can override any field under values — service.type, image.repository, env variables, and so on. You can also override non-values fields like version, url, or timeout using the step-level configuration (see below).

To discover what you can override, inspect the krateo.*.yaml file for your target type and look at the with.values of each step you want to customize.

The base krateo.yaml groups steps into logical components via componentsDefinition:

componentsDefinition:
  cnpg:
    steps:
      - install-cnpg
      - install-pg-cluster
  frontend:
    steps:
      - install-frontend

A profile addresses a component by name and targets a specific step within it via stepConfig:

components:
  <component-name>:         # must match a key in componentsDefinition
    enabled: false          # (optional) disable the entire component
    stepConfig:
      <step-id>:            # must match a step id in that component's steps list
        with:
          values:           # deep-merged into the step's existing .with.values
            <path>: <new-value>

The enabled: false flag is a convenience shortcut: it skips all steps belonging to that component. You can see this in the no-cnpg and no-finops built-in profiles.

The with.values content is deep-merged — you only need to specify the leaf keys you want to change; the rest of the base configuration is preserved.

2. Step-level configuration (advanced)​

If you need even finer control — for example, to change a non-values field like the chart version, URL, or timeout — you can override at the step level directly:

steps:
  - id: <step-id>
    skip: true              # skip this specific step
    with:
      version: <new-version>
      values:
        <path>: <new-value>

Step-level overrides take precedence over component-level ones.

Merge semantics​

krateoctl applies overlays in this exact order, each one deep-merged into the previous result:

  1. Base config (krateo.yaml or krateo.<type>.yaml)
  2. Generic overrides file (krateo-overrides.yaml) — if present
  3. Each profile from --profile, left to right

Since the merge is recursive, providing only the leaf path cluster.instances: 5 is enough to change that single field without touching cluster.storage, cluster.resources, or any other sibling key.

Practical examples​

Example 1: Override CNPG cluster size and storage​

Suppose you want 5 PostgreSQL instances (default 3) with 50Gi storage (default 10Gi).

Create krateo-overrides.large-pg.yaml:

components:
  cnpg:
    stepConfig:
      install-pg-cluster:
        with:
          values:
            cluster:
              instances: 5
              storage:
                size: 50Gi

Apply it:

krateoctl install apply --version 3.0.0 --profile large-pg

All other CNPG settings (resources, roles, databases) remain unchanged.

Example 2: Change the frontend service port and add a custom environment variable​

Create krateo-overrides.custom-frontend.yaml:

components:
  frontend:
    stepConfig:
      install-frontend:
        with:
          values:
            service:
              nodePort: 31000
            config:
              MY_CUSTOM_VAR: "hello"

Apply:

krateoctl install apply --version 3.0.0 --type nodeport --profile custom-frontend

Example 3: Disable a component and override another​

Combine built-in and custom profiles. Create krateo-overrides.prod-tweaks.yaml:

components:
  resources-stack:
    stepConfig:
      install-resources-ingester:
        with:
          values:
            config:
              DEBUG: "true"

Then run with multiple profiles:

krateoctl install apply --version 3.0.0 --profile no-finops,prod-tweaks

FinOps is disabled (from the built-in no-finops profile), and resources-ingester debug is enabled (from your prod-tweaks profile).

Example 4: Configure Ingress host and TLS​

In Krateo 2.7, Ingress host and TLS were configured via Helm values. In Krateo 3, the same customization is done through profiles.

Create krateo-overrides.ingress-tls.yaml:

components:
  backend:
    stepConfig:
      install-authn:
        with:
          values:
            ingress:
              enabled: true
              className: nginx
              annotations:
                cert-manager.io/cluster-issuer: letsencrypt-prod
              hosts:
                - host: authn.krateo.example.com
                  paths:
                    - path: /
                      pathType: ImplementationSpecific
              tls:
                - secretName: authn-tls-secret
                  hosts:
                    - authn.krateo.example.com
      install-snowplow:
        with:
          values:
            ingress:
              enabled: true
              className: nginx
              annotations:
                cert-manager.io/cluster-issuer: letsencrypt-prod
              hosts:
                - host: snowplow.krateo.example.com
                  paths:
                    - path: /
                      pathType: ImplementationSpecific
              tls:
                - secretName: snowplow-tls-secret
                  hosts:
                    - snowplow.krateo.example.com
  events-stack:
    stepConfig:
      install-events-presenter:
        with:
          values:
            ingress:
              enabled: true
              className: nginx
              annotations:
                cert-manager.io/cluster-issuer: letsencrypt-prod
              hosts:
                - host: events.krateo.example.com
                  paths:
                    - path: /
                      pathType: ImplementationSpecific
              tls:
                - secretName: events-tls-secret
                  hosts:
                    - events.krateo.example.com
  frontend:
    stepConfig:
      install-frontend:
        with:
          values:
            ingress:
              enabled: true
              className: nginx
              annotations:
                cert-manager.io/cluster-issuer: letsencrypt-prod
              hosts:
                - host: krateo.example.com
                  paths:
                    - path: /
                      pathType: ImplementationSpecific
              tls:
                - secretName: frontend-tls-secret
                  hosts:
                    - krateo.example.com

Preview the diff between the default ingress configuration and your profile:

krateoctl install plan --version 3.0.0 --type ingress --profile ingress-tls

The plan command outputs only the differences between the base configuration and the profile, so you can verify exactly what will change before applying.

Apply:

krateoctl install apply --version 3.0.0 --type ingress --profile ingress-tls

Example 5: Step-level skip​

Create krateo-overrides.skip-portal.yaml:

steps:
  - id: install-portal
    skip: true

This bypasses the portal chart installation without modifying any component definition.

Persistence warning​

Profiles are not snapshotted as part of the installation — krateoctl only remembers the computed execution steps. If you omit --profile on a subsequent apply, those overridden values are lost and the step reverts to the defaults from krateo.yaml.

Always use plan --diff-installed with the same flags you intend to apply with, and keep your profile list documented in your environment's runbooks.

For the full CLI reference, run:

krateoctl install apply -h

Installation Snapshot​

krateoctl saves the resolved installation state as an Installation custom resource in the krateo.io/v1 API group.

The snapshot contains:

  • the resolved componentsDefinition
  • the computed steps
  • the installationVersion used to build it

By default, the snapshot is stored with the name krateoctl in the install namespace.

How It Is Used​

  • krateoctl install apply saves the snapshot after a successful apply.
  • krateoctl install plan --diff-installed loads the stored snapshot and compares it with the newly computed plan.
  • krateoctl install migrate-full also saves the snapshot as part of the automatic migration flow.

Why It Exists​

The snapshot gives krateoctl a durable record of what was last computed and applied. That makes it easier to:

  • compare a new release against the current state
  • detect drift between the installed workflow and the newly computed one
  • keep a versioned record of the installation logic that produced the cluster state

Notes​

  • The snapshot resource is namespaced.
  • The CRD is installed automatically by krateoctl install apply and the migration flow if it is missing.
  • If the snapshot is not present, plan --diff-installed reports that it could not find one and continues without a diff.

Secrets​

Secrets are managed separately from the install workflow. The recommended approach is to store them in Vault and sync them into Kubernetes.

See the full Secrets Spec for the required names, keys, and namespace rules.

Plan Command​

krateoctl install plan is the command that loads the configuration, computes the workflow, and prints the result as multi-document YAML or as a diff summary.

tip

Always run plan before apply to inspect the changes and avoid unexpected configuration modifications.

Usage​

krateoctl install plan [FLAGS]

Key Flags​

  • --version release tag to fetch from the releases repository
  • --repository custom GitHub repository URL for release assets, default https://github.com/krateoplatformops/releases
  • --config local configuration file, default krateo.yaml
  • --profile optional profile name, such as dev or prod
  • --namespace target namespace for the installation (default krateo-system). Use this to install Krateo in a namespace different from the default, or to run parallel installations in separate namespaces
  • --type file variant to use, such as nodeport, loadbalancer, or ingress
  • --diff-installed compare the computed plan against the stored installation snapshot
  • --diff-format choose how diffs are rendered; use table for a per-step summary view
  • --output emit the computed plan as YAML to stdout
  • --skip-validation skip configuration validation
  • --debug enable debug logging, or set KRATEOCTL_DEBUG

How It Works​

  1. Resolve Main Config: Loads the configuration file. If --type is specified (e.g., nodeport), it looks for krateo.nodeport.yaml. If not found, or if no type is specified, it falls back to krateo.yaml.
  2. Apply Overrides: Applies krateo-overrides.yaml and any profile-specific overrides (krateo-overrides.<profile>.yaml) if --profile is present.
    • When --profile is used (e.g., --profile dev,test), krateoctl looks for krateo-overrides.<profile>.yaml files.
    • In remote mode (--version set): searches the releases repository first, then falls back to local files if not found.
    • In local mode (no --version): searches only local files.
  3. Resolve Hooks: Selects type-specific pre/post upgrade hooks (e.g., pre-upgrade.nodeport.yaml) with a fallback to generic ones (e.g., pre-upgrade.yaml).
  4. Compute Workflow: Processes all gathered definitions and computes the execution plan.
  5. Diff (Optional): If --diff-installed is used, compares the computed plan against the last saved installation snapshot.

Understanding --diff-installed​

The --diff-installed flag controls the output mode of the plan command:

  • Without --diff-installed (Default): Generates and displays the execution plan (the sequence of steps) that krateoctl would perform based on the resolved configuration (including overrides and profiles).

    • When you use --profile, the output shows the differences between the base configuration and the profile — only the steps and values that the profile changes.
    • Use this to preview the installation workflow and verify that your profile overrides are correctly interpreted.
    • Useful for verifying that your configuration, profiles, and flags (like --type) are correctly interpreted.

  • With --diff-installed: Performs a diff between the newly computed plan and the stored installation snapshot (the state of the last successful apply).

    • Use this to see exactly what will change in the cluster if you run apply.
    • Useful for understanding the impact of an upgrade or a configuration change relative to the current cluster state.

Examples​

# Preview the local installation config
krateoctl install plan
# Preview a specific release version from the default releases repository
krateoctl install plan --version 3.0.0
# Preview from a custom releases repository
krateoctl install plan --version 3.0.0 --repository https://github.com/myorg/krateo-releases
# Compare the plan against the stored snapshot (what changed since last apply)
krateoctl install plan --version 3.0.0 --diff-installed
# Show a step-by-step diff summary in a table
krateoctl install plan --diff-format table
# Preview with a profile from local files
krateoctl install plan --profile dev
# Preview with a profile from a release version (searches repository first, then local)
krateoctl install plan --version 3.0.0 --profile dev
# Preview with multiple profiles (all profiles use remote-first, local-fallback)
krateoctl install plan --version 3.0.0 --profile dev,aws-lb-hostname
# Preview installation in a custom namespace
krateoctl install plan --version 3.0.0 --namespace krateo-prod

Apply Command​

krateoctl install apply is the command that executes the computed workflow against the cluster.

warning

Profiles and Versions Affect Your Configuration

When you run apply, the combination of --version, --type, and --profile flags directly determines which configuration values are applied:

  1. Changing profiles or versions replaces values — If you used --profile dark-theme in one apply and --profile light-theme in the next apply, all values from the previous dark-theme profile will be replaced with light-theme values.

  2. Omitting a profile removes its configuration — If you used --profile dark-theme initially and then run apply without it, the dark-theme configuration is lost and reverts to defaults.

  3. Always use plan to inspect changes — Always run krateoctl install plan (with the same flags you'll use for apply) before actually running apply, so you can review the changes and confirm they are expected.

Usage​

krateoctl install apply [FLAGS]

Key Flags​

  • --version release tag to fetch from the releases repository
  • --repository custom GitHub repository URL for release assets, default https://github.com/krateoplatformops/releases
  • --config local configuration file, default krateo.yaml
  • --namespace target namespace for the installation (default krateo-system). Use this to install Krateo in a namespace different from the default, or to run parallel installations in separate namespaces
  • --type file variant to use, such as nodeport, loadbalancer, or ingress
  • --profile optional profile name
  • --skip-validation skip configuration validation
  • --debug enable debug logging, or set KRATEOCTL_DEBUG

What apply Does​

  1. Loads the configuration in local or remote mode.
  2. Ensures the Installation CRD exists.
  3. Applies any pre-upgrade manifests first.
  4. Runs the main workflow steps.
  5. Applies any post-upgrade manifests after the workflow completes.
  6. Saves the resulting installation snapshot.

Examples​

# Apply from the local configuration
krateoctl install apply
# Apply a tagged release from the default releases repository
krateoctl install apply --version 3.0.0
# Apply a tagged release and use a custom repository
krateoctl install apply --version 3.0.0 --repository https://github.com/myorg/krateo-releases
# Apply with a type-specific layout
krateoctl install apply --config ./krateo.yaml --type ingress
# Apply with a profile (preview first with: krateoctl install plan --version 3.0.0 --profile dark-theme)
krateoctl install apply --version 3.0.0 --profile dark-theme
# Apply in a custom namespace (for parallel installations or migration scenarios)
krateoctl install apply --version 3.0.0 --namespace krateo-prod

Upgrade Flow​

For a safe upgrade workflow, always follow this sequence:

tip

Recommended Safe Upgrade Workflow

  1. Run krateoctl install plan --version <tag> --diff-installed to compare the target release with the stored installation snapshot.

    • This shows you exactly what changed since your last apply
    • Review the diff carefully before proceeding

  2. Verify your --profile and --type flags are correct

    • If you previously used --profile, include it again or the profile configuration will be lost
    • If you're changing profiles, understand that existing values will be replaced

  3. Run krateoctl install apply --version <tag> with the same flags you used in plan

    • This ensures the configuration matches what you previewed

  4. Verify the upgrade succeeded

    • Check pod status and events in your namespace

General Upgrade Guidelines:

  • Keep --repository pointed at https://github.com/krateoplatformops/releases unless you mirror the release assets elsewhere
  • Use --type to match the target environment layout, such as nodeport, loadbalancer, or ingress
  • Use --diff-installed when you want to compare against the stored snapshot (what changed since last apply)
  • Omit --diff-installed if you want to see the diff against the configuration file instead

Profile Best Practices:

  • Document which profiles you are using in your environment
  • Always include --profile in both plan and apply commands if you're using profiles
  • Never omit a profile in apply if it was used in previous applies, or the configuration will revert to defaults
  • When changing profiles, use plan --diff-installed to see the full impact before applying

Notes​

  • Local mode uses files from disk and is the right fit when you are developing or testing a config change.
  • Remote mode uses the releases repository and is the right fit when you are upgrading to an existing tagged release.