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

This guide covers installing 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:

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:

• Docker
• kubectl
• Helm v3 or later
• preflight and support-bundle kubectl plugins

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. 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:

   Platform	Recommended StorageClass	Performance tier
   Amazon EKS	gp3 or gp2	General purpose SSD
   Azure AKS	managed-csi or default	Standard SSD
   OpenShift	gp2 or platform-specific	Platform-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.

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:

   • Basic configuration: For simple deployments, development, or testing environments.
   • Complete configuration: For production deployments requiring external storage, logging, and TLS.

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

2. Replace the placeholders in the YAML file with the following:

   • <REGISTRY_IP> with your air-gapped registry IP address. For example, 172.31.32.174.
   • <TENANT_FQDN> (basic configuration) or <FQDN> (complete configuration) with your internal domain name. For example, chef360.example.com.
   • <PORT> (basic configuration only) with the port for accessing Chef 360 Platform. For example, 31000. The complete configuration uses port 31000 by default.
   • <TENANT_SLUG> with a unique tenant identifier. For example, example-org-123.
   • <ORGANIZATION_NAME> with your organization name. For example, ExampleOrganization.
   • <ADMIN_EMAIL> with the administrator email address. For example, admin@example.com.
   • <ADMIN_PASSWORD> (basic configuration only) with the administrator password. For example, admin-password.
   • <SMTP_USERNAME> (complete configuration only) with the SMTP authentication username. For example, noreply@example.com.
   • <SMTP_PASSWORD> (complete configuration only) with the SMTP authentication password. For example, smtp-password.
   • <SENDER_EMAIL> with the email sender address. For example, chef360@example.com.
   • <FIRST_NAME> with the admin user’s first name. For example, John.
   • <LAST_NAME> with the admin user’s last name. For example, Doe.
   • <CHEF_360_PLATFORM_LICENSE> with your base64-encoded Chef 360 Platform license.
   • <STORAGE_CLASS> with the Kubernetes StorageClass name. For example, gp3 or gp2 on Amazon EKS.
   • <PRIVATE_REGISTRY> with your private registry endpoint. For example, 198.51.100.0:5000.
   • <*_VERSION> with the component version tags from the Chef 360 Platform Enterprise Portal.
   • Optional: <ROOT_CA_CERTIFICATE> (complete configuration only) with your root CA certificate if you’re using a private CA for TLS.

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:

• Install CLI tools using internal distribution methods.
• Configure node management settings for air-gapped operations.
• Enroll nodes using internal enrollment processes.
• Review administration features relevant to your air-gapped environment.