Install Puppet applications using PAM on a customer-supported Kubernetes cluster

Use these instructions to install Puppet Application Manager and any Puppet applications on an existing Kubernetes cluster.

Before you begin
  1. If you haven’t already done so, install kubectl.
  2. Puppet Application Manager is expected to work on any certified Kubernetes distribution that meets the following requirements. We validated and support:

    • Google Kubernetes Engine

    • AWS Elastic Kubernetes Service

    If you use a different distribution, contact Puppet Support for more information on compatibility with PAM.

  3. Make sure your Kubernetes cluster meets the minimum requirements:
    • Kubernetes version 1.24-1.26.
    • A default storage class that can be used for relocatable storage.
    • A standard Ingress controller that supports websockets (we have tested with Project Contour and NGINX).
    • We currently test and support Google Kubernetes Engine (GKE) clusters.
    Note: If you’re using self-signed certificates on your Ingress controller, you must ensure that your job hardware nodes trust the certificates. Additionally, all nodes that use Continuous Delivery for PE webhooks must trust the certificates, or SSL checking must be disabled on these nodes.
    Important: If you are installing Puppet Comply on Puppet Application Manager, the ingress controller must be configured to allow request payloads of up to 32 MB. Ingress controllers used by Amazon EKS commonly default to a 1 MB maximum — this causes all report submissions to fail.

    The ingress must have a generous limit for total connection time. Setting the connection timeout to infinity in conjunction with an idle timeout is recommended.

  4. If you are setting up Puppet Application Manager behind a proxy server, the installer supports proxies configured via HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables.
    Restriction: Using a proxy to connect to external version control systems is currently not supported.

Installation takes several (mostly hands-off) minutes to complete.

  1. Install the KOTS (Kubernetes off-the-shelf software) plugin on a workstation that has kubectl access to the cluster. Your kubectl configuration must have sufficient privileges to create cluster-level roles and permissions: 
    curl https://kots.io/install | bash
  2. If you are performing an offline install, ensure the required images are available in a local registry.
    1. Download the release assets matching the CLI version using the following command: 
      curl -LO https://github.com/replicatedhq/kots/releases/download/v$(kubectl kots version | head -n1 | cut -d' ' -f3)/kotsadm.tar.gz
    2. Extract the images and push them into a private registry. Registry credentials provided in this step must have push access. These credentials are not stored anywhere or reused later. 
      kubectl kots admin-console push-images ./kotsadm.tar.gz <private.registry.host>/puppet-application-manager \
--registry-username <rw-username> \
--registry-password <rw-password>
    3. Install Puppet Application Manager using images pushed in the previous step. Registry credentials provided in this step only need to have read access, and they are stored in a Kubernetes secret in the current namespace. These credentials are used to pull the images. 
      kubectl kots install puppet-application-manager \
--kotsadm-namespace puppet-application-manager \
--kotsadm-registry <private.registry.host> \
--registry-username <ro-username> \
--registry-password <ro-password>
      Note: If you are setting up Puppet Application Manager behind a proxy server, add the --copy-proxy-env flag to this command to copy the proxy-related environment values from your environment.
    4. You can use similar commands to upload images from the application bundle to your registry to continue to use read-only access when pulling images. Use the same registry namespace (puppet-application-manager) to pull application images. 
      kubectl kots admin-console push-images ./<application-release>.airgap <private.registry.host>/puppet-application-manager \
--registry-username <rw-username> \
--registry-password <rw-password>
  3. To perform an online install of Puppet Application Manager on your cluster, run the following commands from a workstation that has kubectl access to the cluster. 
    kubectl kots install puppet-application-manager --namespace <target namespace>

    This installs Puppet Application Manager on the cluster and sets up a port forward on the ClusterIP.

  4. Navigate to http://localhost:8800 and follow the prompts to be guided through the process of uploading a license for the application, configuring a local registry (for offline installs), checking to make sure your infrastructure meets system requirements, and configuring the application.
    Note: If you are performing an offline install, download the application bundle and provide it when prompted.
    Tip: Clusters like GKE often restrict ports to 30000-32767. The webhook for Continuous Delivery for PE defaults to port 8000. To update this port to something in the allowed range, when configuring the application, use the following steps:
    1. On the Puppet Application Manager Dashboard page, under Config > Optional configuration, select View options for using a proxy or external load balancer.
    2. Enter a new value for Webhook service port.
  5. To use cert-manager, in the Customize endpoints section, select I have cert manager and in the annotations section, add yours. For example: 
    kubernetes.io/ingress.class: nginx
                    cert-manager.io/cluster-issuer: letsencrypt-prod
  6. When you are happy with your configuration, click Save config to deploy the application.
What to do next

Follow the instructions for configuring and deploying your Puppet applications on Puppet Application Manager. For general information, go to Install applications via the PAM UI.

For more information on installing Continuous Delivery for PE online, see Install Continuous Delivery for PE.

For more information on installing Comply online, see Install Comply online.