Skip to main content

Install Chef 360 Platform in a Bring Your Own Kubernetes (BYOK) deployment

This guide explains how to install Chef 360 Platform on your own Kubernetes cluster with internet connectivity. In a standard Bring Your Own Kubernetes (BYOK) installation, Chef 360 Platform can access external resources during installation and operation. Chef 360 Platform provides the application components and orchestration, allowing you to use your existing Kubernetes infrastructure and operational practices.

This guide focuses on common Kubernetes platforms, including Amazon EKS, Azure AKS, and Red Hat OpenShift, covering cluster prerequisites, storage configuration, and a streamlined installation process.

Prerequisites

Before you begin, review the BYOK system requirements.

You need the following:

  • A Chef 360 Platform authorization code
  • A valid Chef 360 Platform license
  • Access to the Chef 360 Platform Enterprise Portal—contact your customer representative to request access.

You need the following applications installed on your workstation:

Deploy Chef 360 Platform on your Kubernetes cluster

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

  1. Configure your cluster
  2. Install Chef 360 Platform
  3. Verify the installation

Configure your 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>

Install Chef 360 Platform

To install Chef 360 Platform on your cluster, follow these steps:

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

  2. In the Helm values YAML file that you downloaded, populate the blank values that are intentionally left empty in the template, using the real values for your environment.

    Both sample files mark every field you must set with a REQUIRED comment, and fields that aren’t required but are suggested 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-basic.yaml

    At a minimum, set the following:

    • tenants[0].tenant.fqdn with your domain name or IP address. For example, chef360.example.com.
    • tenants[0].tenant.slug with a unique tenant identifier. For example, company-dev-01.
    • 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.
    • global.storageClass with the Kubernetes StorageClass name. For example, gp3 or gp2 on Amazon EKS.
    • tenants[0].tenant.license_base64 with your base64-encoded Chef 360 Platform license.yaml file, 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.

  3. Configure Helm to access the Chef 360 Platform registry:

    export CHEF360_REGISTRY_USERNAME="<USERNAME>"
export CHEF360_REGISTRY_PASSWORD="<AUTHORIZATION_CODE>"

    Replace:

    • <USERNAME> with your username. For example, email@example.com.
    • <AUTHORIZATION_CODE> with your authorization code.

    Log in to the Chef 360 Platform registry:

    printf "%s" "$CHEF360_REGISTRY_PASSWORD" | helm registry login registry.chef360.chef.io \
  --username "$CHEF360_REGISTRY_USERNAME" --password-stdin

  4. Get your installation values from the Chef 360 Platform Enterprise Portal.

    Sign in to the Chef 360 Platform Enterprise Portal to get your customer-specific installation values. The portal provides the following values for your installation:

    • Channel: <CHANNEL>
    • Version: <VERSION>
    • Registry: oci://registry.chef360.chef.io/chef-360/

  5. Export the values to the environment along with the Helm values YAML file path:

    export CHEF360_CHANNEL="<CHANNEL>"
export CHEF360_VERSION="<VERSION>"
export CHEF360_VALUES_FILE="<VALUES_YAML>"

    Replace:

    • <CHANNEL> with the target channel. For example, stable.
    • <VERSION> with the target version. For example, v1.7.1.
    • <VALUES_YAML> with the file path. For example, ./helm-values-chef-360-basic.yaml.

  6. Run preflight checks to verify that your cluster meets the requirements:

    helm template oci://registry.chef360.chef.io/chef-360/${CHEF360_CHANNEL}/chef-360 \
  --version $CHEF360_VERSION -f $CHEF360_VALUES_FILE | kubectl preflight -

  7. Install Chef 360 Platform into a new namespace:

    helm install infrastructure-crds oci://registry.chef360.chef.io/chef-360/${CHEF360_CHANNEL}/infrastructure-crds \
  --version 0.1.0 && \
helm install chef-360 oci://registry.chef360.chef.io/chef-360/${CHEF360_CHANNEL}/chef-360 \
  --version $CHEF360_VERSION -f $CHEF360_VALUES_FILE \
  --timeout 30m \
  -n <NAMESPACE> --create-namespace

    Replace <NAMESPACE> with the Kubernetes namespace to install Chef 360 Platform into. For example, chef-360.

  8. Optional: Monitor your deployment with the following commands:

    • Watch pod status in real time:

      kubectl get pods -w -n <NAMESPACE>

    • Check for recent cluster events:

      kubectl get events -n <NAMESPACE> --sort-by=.lastTimestamp

Verify your installation

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

  1. Check that the Chef 360 Platform pods are running:

    kubectl get pods -n <NAMESPACE>

    Replace <NAMESPACE> with the namespace where you installed Chef 360 Platform, for example chef-360.

    A healthy installation shows:

    • All the Chef 360 Platform pods in Running or Completed status
    • No pods in CrashLoopBackOff or ImagePullBackOff states
    • Restart counts are 0 or low

  2. Confirm that all the Chef 360 Platform persistent volume claims (PVCs) are bound:

    kubectl get pvc -n <NAMESPACE>

    Replace <NAMESPACE> with the namespace where you installed Chef 360 Platform, for example chef-360.

    Verify the following:

    • All the Chef 360 Platform PVCs show Bound status
    • The PVCs are bound to persistent volumes (PVs) through the default StorageClass
    • Storage requests match expected sizes

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

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

Troubleshooting

Diagnose issues with a running deployment

To diagnose issues with a running Chef 360 Platform deployment, generate a support bundle that captures a comprehensive snapshot of your cluster:

kubectl support-bundle

The support bundle is a compressed file that contains:

  • Cluster information and logs
  • Pod status and configurations
  • Network and storage details
  • Chef 360 Platform-specific diagnostics

Next steps

After you install Chef 360 Platform:

Thank you for your feedback!

×