Skip to main content

Install Chef 360 Platform Server in your own air-gapped Kubernetes environment

This guide explains how to install Chef 360 Platform Server on an existing Kubernetes cluster (BYOK) in an air-gapped environment. Air-gapped installations don’t have direct internet access and require you to transfer all installation artifacts and host them in the air-gapped environment.

How air-gapped installation works

The following diagram shows the flow of artifacts from Progress Chef’s registries to your air-gapped Kubernetes cluster:

SCrtheeegpIfins1t3t:e6rr0idhneoeePscltlkmaetrpfuoplrulmll/StDHkeWoeupoclbrkme2kec:srttldhaoetclikmoenrpupsuhsh/SteApiPrrre3-ig:gviaasipttmdperaueygrdeinepgnuvliilnrsoKctn8lamsuleslntter

During the air-gapped deployment, the following happens:

  1. From an internet-connected workstation, you pull container images and Helm charts from Chef 360 Platform registries and Chef’s Enterprise Portal.

  2. You then re-tag and push these artifacts to a private registry in your air-gapped environment.

  3. In the air-gapped environment, you deploy Chef 360 Platform on your Kubernetes cluster using the images in your private registry.

Prerequisites

Before you begin, review the BYOK system requirements.

You need the following:

  • A Chef 360 Platform authorization code provided by Progress Software.
  • A valid Chef 360 Platform license.
  • Access to Chef 360 Platform Enterprise Portal—contact your customer representative for access to the portal.

You need the following applications installed on your internet-connected workstation:

Deploy Chef 360 Platform on your Kubernetes cluster

The installation requires coordinating artifacts across two environments: an internet-connected workstation and the air-gapped cluster.

To deploy Chef 360 Platform, complete the following steps in order:

  1. Configure your Kubernetes cluster

  2. Prepare your air-gapped environment

  3. Configure your internet-connected workstation:

    1. Download all container images and Helm charts
    2. Push artifacts to air-gapped registry

  4. If your private registry requires authentication, create an image pull secret.

  5. Install Chef 360 Platform in the air-gapped environment:

    1. Create a configuration file for the air-gapped deployment
    2. Run preflight checks
    3. Install Chef 360 Platform using local registry

Configure your Kubernetes cluster

To prepare your cluster for installation, follow these steps:

  1. Configure kubectl to connect to your target cluster, then verify that all nodes are Ready:

    kubectl get nodes
kubectl get pods -A

    All nodes must show Ready status and all control plane components must show Running status.

  2. Verify that your cluster has a default StorageClass:

    kubectl get storageclass

    Look for the (default) annotation next to your desired storage class. Ensure exactly one StorageClass is marked as default—multiple defaults can cause persistent volume claim (PVC) binding failures.

    If no default StorageClass exists or you need to change it, run the following command:

    kubectl patch storageclass <STORAGE_CLASS_NAME> \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

    The following table lists recommended storage classes for common platforms:

    PlatformRecommended StorageClassPerformance tier
    Amazon EKSgp3 or gp2General purpose SSD
    Azure AKSmanaged-csi or defaultStandard SSD
    OpenShiftgp2 or platform-specificPlatform-specific

  3. Optional: For cloud platforms that require load balancer configuration, set up external access according to your platform’s requirements. See the network requirements.

  4. Optional: For Tiered and Hyperscaled HA deployments, label nodes to control how Chef 360 Platform components are scheduled:

    kubectl label node <NODE_ID> <LABEL_KEY>=<LABEL_VALUE>

Prepare the air-gapped environment

To set up the private container registry that stores all Chef 360 Platform components, follow these steps. This example uses Docker Registry, but you can use any compatible container registry solution.

  1. Start your local container registry.

    Your air-gapped environment needs a local registry to host all Chef 360 Platform images and charts. This registry replaces internet access to Docker Hub and Chef registries.

    To start the Docker registry service, run the following:

    docker run -d -p 5000:5000 --restart=always --name registry registry:2

    This creates a local Docker registry listening on port 5000 that automatically restarts if the machine reboots.

  2. Get your machine’s IP address:

    hostname -I

    The output is an IP address like 192.168.1.100 or 10.0.1.50. Note this IP address and port number; you use them throughout the rest of this guide. For example, if this command returned 192.168.1.100, then your registry endpoint is 192.168.1.100:5000.

    Your workstation uses this IP address to push artifacts to the registry.

  3. Confirm your registry is working and can accept connections:

    docker ps | grep registry
curl http://<REGISTRY_IP>:5000/v2/_catalog

    If the registry is accessible:

    • docker ps shows a registry container running on port 5000
    • curl returns an empty but valid JSON string: {"repositories":[]}

    If this step fails, check firewall settings and ensure port 5000 is accessible from your workstation.

Download images from Chef 360 Platform Enterprise Portal

The Enterprise Portal generates customized installation commands and download URLs for your air-gapped environment.

To pull images from the Chef 360 Platform Enterprise Portal, follow these steps:

  1. From your internet-connected workstation, access the Chef 360 Platform Enterprise Portal.

  2. In the Enterprise Portal, go to your customer configuration:

    1. Select No outbound requests allowed (air gap) to set your cluster’s network availability.

      This setting tells the portal that your Kubernetes cluster can’t reach the internet, which changes how installation packages are generated.

    2. Select My workstation can access the internet, the registry, and the cluster.

      This indicates that the workstation acts as a bridge for transferring artifacts.

    3. In the Registry URI field, enter your air-gapped registry endpoint:

      For example, 192.168.1.100:5000.

    The Enterprise Portal generates air-gapped-specific download commands for container images, Helm chart pull commands, and installation instructions.

  3. Follow the instructions in the Enterprise Portal.

  4. Correct the docker pull commands for public Docker Hub images from the Chef 360 Platform proxy registry. Add the library/ path segment after docker.io/ in each command:

    Replace these:

    docker pull proxy.chef360.chef.io/anonymous/docker.io/busybox:stable-uclibc
docker pull proxy.chef360.chef.io/anonymous/docker.io/memcached:<VERSION>
docker pull proxy.chef360.chef.io/anonymous/docker.io/nginx:<VERSION>
docker pull proxy.chef360.chef.io/anonymous/docker.io/postgres:<VERSION>

    with these:

    docker pull proxy.chef360.chef.io/anonymous/docker.io/library/busybox:stable-uclibc
docker pull proxy.chef360.chef.io/anonymous/docker.io/library/memcached:<VERSION>
docker pull proxy.chef360.chef.io/anonymous/docker.io/library/nginx:<VERSION>
docker pull proxy.chef360.chef.io/anonymous/docker.io/library/postgres:<VERSION>

  5. On your workstation, run the image pull commands from the Enterprise Portal along with the corrected commands from the previous step.

  6. After downloading all the images, tag each image using the following pattern:

    docker tag proxy.chef360.chef.io/anonymous/docker.io/library/busybox:stable-uclibc \
  <REGISTRY_IP>:5000/library/busybox:stable-uclibc

docker tag proxy.chef360.chef.io/anonymous/docker.io/library/memcached:<VERSION> \
  <REGISTRY_IP>:5000/library/memcached:<VERSION>

docker tag proxy.chef360.chef.io/anonymous/docker.io/library/nginx:<VERSION> \
  <REGISTRY_IP>:5000/library/nginx:<VERSION>

docker tag proxy.chef360.chef.io/anonymous/docker.io/library/postgres:<VERSION> \
  <REGISTRY_IP>:5000/library/postgres:<VERSION>

  7. Push each tagged image to your air-gapped registry:

    docker push <REGISTRY_IP>:5000/library/busybox:stable-uclibc
docker push <REGISTRY_IP>:5000/library/memcached:<VERSION>
docker push <REGISTRY_IP>:5000/library/nginx:<VERSION>
docker push <REGISTRY_IP>:5000/library/postgres:<VERSION>

    Monitor the air-gapped machine to ensure it’s receiving the images.

  8. Optional: Verify the transfer on your air-gapped machine:

    curl http://<REGISTRY_IP>:5000/v2/_catalog

    The output lists repositories including library/busybox, library/nginx, and other transferred images.

Create an image pull secret

If your private registry requires authentication, create an image pull secret so Kubernetes can pull images from it during installation. Skip this section if your private registry doesn’t require authentication, such as the example registry started in Prepare the air-gapped environment.

  1. If you’re using a namespace for the Chef 360 Platform deployment, create it first:

    kubectl create namespace <NAMESPACE>

  2. Create the image pull secret.

    kubectl create secret docker-registry regcred \
  --docker-server=<PRIVATE_REGISTRY> \
  --docker-username=<REGISTRY_USERNAME> \
  --docker-password=<REGISTRY_PASSWORD> \
  --namespace <NAMESPACE>

    Replace the following:

    • <PRIVATE_REGISTRY> with your private registry server address. For example, 192.168.1.100:5000.
    • <REGISTRY_USERNAME> with your registry username.
    • <REGISTRY_PASSWORD> with your registry password.
    • <NAMESPACE> with the namespace where you install Chef 360 Platform.

    Every Chef 360 Platform Helm chart component, including the Replicated SDK component, expects this secret to be named regcred in the namespace where you install Chef 360 Platform.

Install Chef 360 Platform in the air-gapped environment

To configure and install Chef 360 Platform in your air-gapped environment using the local artifacts in your registry, follow these steps:

  1. Download a Helm values YAML file that matches your deployment requirements:

    Both files redirect all image pulls to your local registry instead of the internet.

  2. Populate the values that are intentionally left blank in the downloaded YAML file.

    Both sample files mark every field you must set with a REQUIRED comment, and every optional-but-suggested field with a RECOMMENDED comment. Search the file you downloaded for these tags to double-check you haven’t missed a field:

    grep -n -E "REQUIRED|RECOMMENDED" helm-values-chef-360-air-gapped.yaml

    At a minimum, set the following:

    • x-private-repo-root with your air-gapped registry host. Replace <PRIVATE_REGISTRY_HOST> so the value reads, for example, 172.31.32.174:5000/chef-360. The global.ecr and global.docker.* fields reference this value automatically, so you only need to edit them separately if a specific component requires a different registry.
    • tenants[0].tenant.fqdn with your internal domain name. For example, chef360.example.com.
    • tenants[0].tenant.slug with a unique tenant identifier. For example, example-org-123.
    • tenants[0].tenant.name with your organization name. For example, ExampleTenant.
    • tenants[0].tenant.tenant_admin_email with the administrator email address. For example, admin@example.com.
    • tenants[0].tenant.tenant_admin_first_name with the admin user’s first name. For example, John.
    • tenants[0].tenant.tenant_admin_last_name with the admin user’s last name. For example, Doe.
    • If you aren’t using the built-in MailPit defaults, replace tenants[0].tenant.notification_integration_username, notification_integration_password, and notification_integration_senderemail with your real SMTP username, password, and sender address. For example, noreply@example.com, smtp-password, and chef360@example.com.
    • Recommended: global.storageClass with the Kubernetes StorageClass name used by your cluster, such as gp3 or gp2 on Amazon EKS. Leave this value blank to use your cluster’s default StorageClass.
    • tenants[0].tenant.license_base64 with your base64-encoded Chef 360 Platform license, if you’re deploying with a licensed bundle.
    • Optional: In the complete configuration file only, uncomment chef-platform.common-cert-manager.userRootCa and set it to your root CA certificate if you’re using a private CA for TLS. The basic configuration file doesn’t include this field.
    • Populate any remaining component version fields from the Chef 360 Platform Enterprise Portal before running the install commands.

  3. Run preflight checks to validate that your Kubernetes cluster can support Chef 360 Platform.

    The commands for this step are available in the Chef 360 Platform Enterprise Portal.

    If preflight checks fail, review the failure messages and fix any issues before continuing.

  4. Install the infrastructure Custom Resource Definitions (CRDs) and Chef 360 Platform Helm charts.

    The commands for this step are available in the Chef 360 Platform Enterprise Portal.

  5. Use the following commands to monitor the installation progress:

    • Watch pod status in real time:

      kubectl get pods -w

    • Check for recent cluster events:

      kubectl get events --sort-by=.metadata.creationTimestamp

Verify your installation

After installation completes, verify that Chef 360 Platform is running correctly:

  1. Verify that all pods are running:

    kubectl get pods

    A healthy installation shows:

    • All pods in Running or Completed status
    • No pods in CrashLoopBackOff or ImagePullBackOff states
    • Restart counts at 0 or low

  2. Confirm that you’re receiving email notifications from the Chef 360 Platform notification system.

  3. Verify that the tenant is accessible through the web UI by navigating to your configured domain and port.

Next steps

After you install Chef 360 Platform, sign in using the access URL from your configuration file (for example, http://chef360.example.com:31000) and complete the following:

Thank you for your feedback!

×