Deployment Cell Amenities¶

Overview¶

Deployment cell amenities are additional infrastructure components (Helm charts) that can be installed and managed on your deployment cell to enhance functionality and provide essential services. Omnistrate provides both managed amenities and support for custom amenities to meet your specific infrastructure requirements.

This guide demonstrates how to manage deployment cell amenities using the Omnistrate command-line tool.

Prerequisites¶

Before managing deployment cell amenities, ensure you have:

• Omnistrate CTL installed (installation guide)
• Valid credentials for the Omnistrate platform
• Appropriate permissions to manage deployment cell
• Access to your target environment (e.g., PROD, STAGING)

Deployment cell support two types of amenities:

Amenities are the right place for components that are cluster-wide rather than instance-specific, such as monitoring stacks, CSI drivers, ingress controllers, shared Operators, and policy controllers. Managing them at the cell layer lets you upgrade them once per cluster instead of tying their lifecycle to every deployment instance.

Managed Amenities¶

Pre-configured Helm charts maintained by Omnistrate that are automatically available for installation. These amenities are:

• Fully managed: Omnistrate handles chart configuration, updates, and maintenance
• Cloud-optimized: Configured with best practices for each cloud provider
• Production-ready: Tested and validated for enterprise use

Common managed amenities include:

• Observability Prometheus: Monitoring and metrics collection
• Kubernetes Dashboard: Web-based Kubernetes cluster management interface
• External DNS: Automatic DNS record management for Kubernetes services
• Cert Manager: Automatic SSL certificate provisioning and renewal
• Nginx Ingress Controller: HTTP/HTTPS traffic routing and load balancing

Each cloud provider has additional managed amenities.

Custom Amenities¶

1. Helm charts that you configure and manage yourself.
2. Plain Kubernetes Manifests that you can deploy and manage on your deployment cell.

Managing Deployment Cell Configuration Templates¶

Configuration templates define which amenities are available for a deployment cell on each cloud provider.

Generate Configuration Template¶

Create a template with all available amenities for a specific cloud provider:

omnistrate-ctl deployment-cell generate-config-template --cloud aws --output template-aws.yaml

When prompted, select your login method and provide credentials.

Using Schema Validation¶

To simplify the definition of this specification file Omnistrate provide a JSON schema that can be used for validation. You can use the JSON schema in IDEs that use the YAML Language Server (eg: VSCode / NeoVim).

# yaml-language-server: $schema=https://api.omnistrate.cloud/2022-09-01-00/schema/deployment-cell-amenities-spec-schema.json

For IntelliJ replace the top line with the following line to set up the yaml schema

# $schema: https://api.omnistrate.cloud/2022-09-01-00/schema/deployment-cell-amenities-spec-schema.json

Review Template Structure¶

The generated template contains two main sections:

# yaml-language-server: $schema=https://api.omnistrate.cloud/2022-09-01-00/schema/deployment-cell-amenities-spec-schema.json

managedAmenities:
  - name: EFS CSI Driver
    description: EFS CSI Driver
    type: Helm
  - name: AWS Load Balancer Controller
    description: AWS Load Balancer Controller
    type: Helm
  - name: Cluster Autoscaler
    description: Cluster Autoscaler
    type: Helm
  # ... additional managed amenities

customAmenities:
  - name: EBS CSI Driver
    description: EBS CSI Driver
    type: Helm
    properties:
      ChartName: "aws-ebs-csi-driver"
      ChartVersion: "2.28.1"
      ChartRepoName: "aws-ebs-csi-driver"
      ChartRepoURL: "https://kubernetes-sigs.github.io/aws-ebs-csi-driver"
      CredentialsProvider:
        Type: "none"
      DefaultNamespace: "kube-system"
      ChartValues:
        image:
          repository: "public.ecr.aws/ebs-csi-driver/aws-ebs-csi-driver"
          tag: "v1.27.0"
        controller:
          replicaCount: 2
          resources:
            requests:
              cpu: "10m"
              memory: "40Mi"
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                - matchExpressions:
                  - key: omnistrate.com/control-plane
                    operator: Exists
          tolerations:
            - key: CriticalAddonsOnly
              value: "true"
              effect: NoSchedule

Helm Chart Amenities¶

When defining custom Helm amenities, include these properties:

Example: install the same chart twice

customAmenities:
  - name: opentelemetry-collector-agents
    description: Node-level collectors
    type: Helm
    properties:
      ChartName: opentelemetry-collector
      ChartVersion: 0.127.2
      ChartRepoName: opentelemetry-community
      ChartRepoURL: https://open-telemetry.github.io/opentelemetry-helm-charts
      DefaultNamespace: observability
      ReleaseName: opentelemetry-collector-agents

  - name: opentelemetry-collector-gateway
    description: Central gateway
    type: Helm
    properties:
      ChartName: opentelemetry-collector
      ChartVersion: 0.127.2
      ChartRepoName: opentelemetry-community
      ChartRepoURL: https://open-telemetry.github.io/opentelemetry-helm-charts
      DefaultNamespace: observability
      ReleaseName: opentelemetry-collector-gateway

Kubernetes Manifest Amenities¶

The KubernetesManifest amenity type allows you to deploy custom Kubernetes manifests to deployment cells. This is useful for deploying Secrets, ConfigMaps, or any other Kubernetes resources that are not covered by Helm chart amenities.

When defining Kubernetes manifest amenities, include these properties:

Each entry in the manifests array must have exactly one of the following:

Example: Inline ConfigMap

customAmenities:
  - name: app-config
    description: Application configuration
    type: KubernetesManifest
    properties:
      manifests:
        - def:
            apiVersion: v1
            kind: ConfigMap
            metadata:
              name: app-config
              namespace: default
            data:
              DATABASE_HOST: postgres.default.svc.cluster.local
              LOG_LEVEL: info

Example: Inline Secret

customAmenities:
  - name: app-secrets
    description: Application secrets
    type: KubernetesManifest
    properties:
      manifests:
        - def:
            apiVersion: v1
            kind: Secret
            metadata:
              name: app-secrets
              namespace: default
            type: Opaque
            stringData:
              API_KEY: my-api-key

Example: Docker Registry Pull Secret

When a chart depends on a private registry, it is often simpler to pre-create the pull secret as a KubernetesManifest amenity and then reference it from the Helm chart values. Store the base64-encoded username:password value in a single Omnistrate secret such as DOCKERHUB_AUTH_B64 and inject it directly into the manifest:

customAmenities:
  - name: ingress-nginx-namespace
    description: Namespace for ingress components
    type: KubernetesManifest
    properties:
      manifests:
        - def:
            apiVersion: v1
            kind: Namespace
            metadata:
              name: ingress-nginx

  - name: ingress-nginx-pull-secret
    description: Pull secret for Docker Hub
    type: KubernetesManifest
    properties:
      manifests:
        - def:
            apiVersion: v1
            kind: Secret
            metadata:
              name: dockerhub-pull-secret
              namespace: ingress-nginx
            type: kubernetes.io/dockerconfigjson
            stringData:
              .dockerconfigjson: |
                {"auths":{"docker.io":{"auth":"$secret.DOCKERHUB_AUTH_B64"}}}

Example: File References

customAmenities:
  - name: external-manifests
    description: Manifests from files
    type: KubernetesManifest
    properties:
      manifests:
        - file: ./manifests/configmap.yaml
        - file: ./manifests/secret.yaml

File paths are resolved relative to the configuration file location.

Example: Mixed Inline and File References

customAmenities:
  - name: mixed-manifests
    description: Mixed inline and file manifests
    type: KubernetesManifest
    properties:
      manifests:
        - file: ./secret.yaml
        - def:
            apiVersion: v1
            kind: ConfigMap
            metadata:
              name: runtime-config
              namespace: default
            data:
              FEATURE_FLAG: "true"

Validation

The CLI validates KubernetesManifest amenities before sending them to the server:

• The manifests array cannot be empty
• Each entry must have either file or def, but not both
• File references must point to valid, readable YAML files
• YAML content must be valid and parseable

Affinity rules and tolerations¶

Omnistrate creates a system node pool that is independent of the service plan node pool. To allow Operators and Controllers to run on the system node pool, affinity rules and tolerations must be defined.

Affinity rules to prevent from running on service nodes:

  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: omnistrate.com/control-plane
            operator: Exists

Toleration to allow to run on system nodes:

  tolerations:
    - key: CriticalAddonsOnly
      value: "true"
      effect: NoSchedule

Update Configuration Template¶

After customizing your template, apply it to your organization:

omnistrate-ctl deployment-cell update-config-template --cloud aws -f template-aws.yaml

View Current Configuration Template¶

Check the current configuration template for your organization:

omnistrate-ctl deployment-cell describe-config-template --cloud aws

For JSON output:

omnistrate-ctl deployment-cell describe-config-template --cloud aws --output json

Managing Individual Deployment Cell Amenities¶

Check Deployment Cell Status¶

View the current amenities and status of a specific deployment cell:

omnistrate-ctl deployment-cell describe-config-template --id hc-xxxxxxx

For JSON output:

omnistrate-ctl deployment-cell describe-config-template --id hc-xxxxxxx --output json

Replace hc-xxxxxxx with your actual deployment cell ID.

Update Deployment Cell Amenities¶

You have two options for updating amenities on a deployment cell:

Option 1: Update with Configuration File¶

Create a custom configuration file:

# yaml-language-server: $schema=https://api.omnistrate.cloud/2022-09-01-00/schema/deployment-cell-amenities-spec-schema.json

managedAmenities:
  - name: Observability Prometheus
    description: Observability Prometheus
    type: Helm
  - name: Kubernetes Dashboard
    description: Kubernetes Dashboard
    type: Helm
  - name: External DNS
    description: External DNS
    type: Helm

customAmenities:
  - name: Custom Chart
    description: Custom application chart
    type: Helm
    properties:
      ChartName: "my-custom-chart"
      ChartVersion: "1.0.0"
      ChartRepoURL: "https://my-repo.example.com"

Apply the configuration:

omnistrate-ctl deployment-cell update-config-template --id hc-xxxxxxx -f custom-config.yaml

Option 2: Sync with Template¶

Automatically sync the deployment cell with your organization's template:

omnistrate-ctl deployment-cell update-config-template --id hc-xxxxxxx --sync-with-template

This command syncs the deployment cell's amenities with the configuration template defined for its environment.

Apply Pending Changes¶

After updating the configuration, apply the changes to trigger actual deployment:

omnistrate-ctl deployment-cell apply-pending-changes --id hc-xxxxxxx

This command:

• Applies any pending amenity additions or removals
• Triggers the deployment/undeployment of Helm charts
• Updates the deployment cell to match the desired configuration

Recommended Patterns for Dependent Amenities¶

Use these patterns when a Helm amenity depends on resources such as namespaces, Secrets, or CRDs:

• If strict ordering is required, prefer a single Helm chart that owns both the prerequisite objects and the application resources.
• If you must separate them, create the prerequisite objects first with KubernetesManifest, apply pending changes, and then run a second amenities sync for the dependent Helm charts.
• If several charts share the same registry credentials, keep the namespace and image pull secret as dedicated manifest amenities and reuse them across charts.
• If the chart can create its own namespace, use DefaultNamespace and chart-native secret creation rather than relying on parallel amenities to line up.

Debugging Amenities Sync¶

When an amenities rollout is stuck or a new template cannot be applied because a sync is still in progress, inspect the active deployment-cell workflows first:

omnistrate-ctl deployment-cell workflow list hc-xxxxxxx
omnistrate-ctl deployment-cell workflow events hc-xxxxxxx <workflow-id>

These commands show whether the cell is still in DEPLOYMENT_CELL_SYNC_AMENITIES, which step is currently active, and the last debug event emitted by the workflow.

If a previous amenities sync is blocking a new update:

• If the sync appears as its own deployment-cell workflow in the UI, cancel that workflow there and rerun the update.
• If the cell sync was triggered indirectly by another workflow, inspect the deployment-cell workflow list first. The parent workflow can finish or fail while the cell sync is still active.
• If the workflow remains stuck and no cancel control is available, wait for the workflow timeout or contact support rather than layering more template changes on top of the same stuck sync.

If the workflow says a Helm amenity failed, connect to the deployment cell and inspect the releases directly:

omnistrate-ctl deployment-cell update-kubeconfig hc-xxxxxxx --role cluster-admin --kubeconfig /tmp/kubeconfig
export KUBECONFIG=/tmp/kubeconfig
helm ls -A
kubectl get pods -A

Use this flow when:

• A sync is still running even though the releases appear installed
• A reverted template still fails because a manifest or release is not reconciling cleanly
• A new update-config-template attempt is blocked by an older sync that is still in progress