ForgeOps

Deploy using Kustomize on minikube

  1. Verify you’ve set up your environment and created a Kubernetes cluster as documented in the setup section.

  2. Use the terminal where you have already activated Python3 virtual environment. If you haven’t already done so, activate the virtual environment in a new terminal window:

    $ source .venv/bin/activate

  3. The configuration of a ForgeOps deployment is steered through the use of Kustomize overlays or Helm values. Use the forgeops env command to set up the Kustomize overlays and Helm values files to configure your ForgeOps deployment environment:

    In a minikube environment, use the single instance deployment. For example:

    $ cd /path/to/forgeops/bin
$ ./forgeops env --env-name my-env --fqdn my-fqdn \
  --cluster-issuer my-cluster-issuer --single-instance

    Learn more about deployment sizes in Cluster and deployment sizes and about single instances here.

  4. Identify Docker images to deploy:

    • If you want to use custom Docker images for the platform, update the image defaulter file with image names and tags generated by the forgeops build command. The image defaulter file is located in your environment (my-env) folder /path/to/forgeops/kustomize/overlay/my-env directory.

      You can get the image names and tags from the image defaulter file on the system on which the customized Docker images were developed.

    • If you want to use ForgeOps-provided Docker images for the platform, do not modify the image defaulter file.

    • Use the forgeops image command to set up the correct component images to be deployed. The following command sets up the latest ForgeOps-provided Docker image for deployment:

      $ cd /path/to/forgeops/bin
$ ./forgeops image --env-name my-env --release 8.0.0 platform

      If you want to set up your deployment environment with your own image, then use the following example command:

      $ cd /path/to/forgeops/bin
$ ./forgeops image --release my-image --release-name my-release --env-name my-env platform

  5. Set up your Kubernetes context:

    1. Create a Kubernetes namespace in the cluster for the Ping Identity Platform pods:

      $ kubectl create namespace my-namespace

    2. Set the active namespace in your Kubernetes context to the Kubernetes namespace you just created:

      $ kubens my-namespace

  6. Set up the certificate and secret management prerequisites:

    1. Since minikube provides its own ingress controller, NGINX controller need not be installed.

    2. The forgeops repository provides cert-manager as the certificate management utility. If you need to use a different certificate management utility, refer to the corresponding documentation for installing that utility.

    3. Currently, the secret agent is used as the default secrets management utility in ForgeOps deployments. You can continue to use the secret agent in existing deployments. In new ForgeOps deployments, you should install and use the secret generator to manage Kubernetes secrets. The secret agent utility will be deprecated in the next release.

    4. Forgeops artifacts include alternatives for secrets management (secret agent or secret-generator) and ingress (nginx or ha-proxy). The forgeops prereqs command provides a corresponding -- option for those components. The -- option isn’t available for components, such as cert-manager, for which an alternative isn’t provided. Some examples are provided in forgeops prereqs command reference.

    1. To install the secret generator for secret management:

      $ forgeops prereqs --secret-generator

    2. To install the secret agent for secret management:

      $ forgeops prereqs

  7. In a separate terminal tab or window, run the minikube tunnel command, and enter your system’s superuser password when prompted:

    $ minikube tunnel
✅  Tunnel successfully started

📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible …​

❗  The service/ingress forgerock requires privileged ports to be exposed: [80 443]
🔑  sudo permission will be asked for it.
❗  The service/ingress ig requires privileged ports to be exposed: [80 443]
🏃  Starting tunnel for service forgerock.
🔑  sudo permission will be asked for it.
🏃  Starting tunnel for service ig.
Password:

    The tunnel creates networking that lets you access the minikube cluster’s ingress on the localhost IP address (127.0.0.1). Leave the tab or window that started the tunnel open for as long as you run the ForgeOps deployment.

    Refer to this post for an explanation about why a minikube tunnel is required to access ingress resources when running minikube on an ARM-based macOS system.

  8. Set up the fast storage class using the minikube-fast-storage-class.yaml file in the /path/to/forgeops/cluster/resources directory:

    $ kubectl apply -f /path/to/forgeops/cluster/resources/minikube-fast-storage-class.yaml

  9. Enable secret generator in your deployment environment:

    $ forgeops env --env-name my-env --namespace my-namespace  --secret-generator
    The secret agent is enabled and used in the environment if the secret generator isn’t enabled.

  10. Run the forgeops apply command. Learn more in forgeops apply command reference.

    For example:

    $ cd /path/to/forgeops/bin
$ ./forgeops apply --env-name my-env

    The preceding command creates a single-instance ForgeOps deployment. Only single-instance deployments are supported on minikube.

    If you prefer not to deploy using a single forgeops apply command, you can find more information in Alternative deployment techniques when using Kustomize.

    Ping Identity only offers its software or services to legal entities that have entered into a binding license agreement with Ping Identity. When you install Docker images provided by ForgeOps, you agree either that: 1) you are an authorized user of a Ping Identity Platform customer that has entered into a license agreement with Ping Identity governing your use of the Ping Identity software; or 2) your use of the Ping Identity Platform software is subject to the Ping Identity Subscription Agreements.

  11. Check the status of the pods in the namespace in which you deployed the platform until all the pods are ready:

    1. Run the kubectl get pods command.

    2. Review the output. Deployment is complete when:

      • All entries in the STATUS column indicate Running or Completed.

      • The READY column indicates all running containers are available. The entry in the READY column represents [total number of containers/number of available containers].

    3. If necessary, continue to query your deployment’s status until all the pods are ready.

  12. (Optional) Install a TLS certificate instead of using the default self-signed certificate in your ForgeOps deployment. Refer to TLS certificate for details.

Alternative deployment techniques when using Kustomize

Staged deployments

If you prefer not to perform a ForgeOps Kustomize deployment using a single forgeops apply command, you can deploy the platform in stages, component by component, instead of deploying with a single command. Staging deployments can be useful if you need to troubleshoot a deployment issue.

Generating Kustomize manifests and using kubectl apply commands

You can generate Kustomize manifests using the forgeops env command, and then deploy the platform using the kubectl apply -k command.

The forgeops env command generates Kustomize manifests for your ForgeOps deployment environment. The manifests are written to the /path/to/forgeops/kustomize/overlay/my-env directory of your forgeops repository clone. Advanced users who prefer to work directly with Kustomize manifests that describe their ForgeOps deployment can use the generated content in the kustomize/overlay/my-env directory as an alternative to using the forgeops command:

  1. Generate an initial set of Kustomize manifests by running the forgeops env command.

  2. Run kubectl apply -k commands to deploy and remove platform components. Specify a manifest in the kustomize/overlay/my-env directory as an argument when you run kubectl apply -k commands.

    1. Use GitOps to manage configuration changes to the kustomize/overlay/my-env directory.

Next step