The forgeops command

forgeops — The new generation utility replaces the previous version of forgeops. The new forgeops utility simplifies deploying and managing Ping Identity Platform components in a Kubernetes cluster.

The previous version of the forgeops utility is not supported in this ForgeOps release. It continues to be supported in ForgeOps 7.5 and 7.4, as long as the corresponding Ping Identity Platform components are supported.

You can create and manage custom overlays and Helm values files for each deployment. You can then apply the overlays or value files appropriately using Kustomize or Helm accordingly.

The forgeops utility lets you:

Use Kustomize natively so you can update and use overlays as expected.
Generate a Kustomize overlay manually when you need the overlay.
Generate Helm value files from the same environment set up.
Build and manage Docker images per overlay to allow different images in an environment.
Create and manage each ForgeOps deployment configuration.
Apply the environment configuration changes using either Kustomize or Helm.

Features in forgeops

Discrete overlays

The current forgeops command has the following limitations:

It generates a Kustomize overlay every time it runs.
It overwrites any post-deployment changes in Kustomize overlays.
It uses the preconfigured patch files and ignores the customizations during deployment.

The forgeops command doesn’t generate overlay files automatically. Instead, overlay files are manually generated as needed.

It is recommended to create an overlay for each environment, such as test, stage, and prod. It is also recommended to create an overlay for each single-instance environment, such as test-single, stage-single, and prod-single. The single-instance overlays help you develop file-based configuration changes, export them, and build new images.

`image-defaulter` in every overlay

Each overlay includes an image-defaulter component. When using Kustomize, you can develop and build and test custom images in your single-instance environment. Once you are satisfied with the image, you can copy the image-defaulter’s kustomization.yaml file into your running overlay.

Sub-overlays

To install and delete individual components, ForgeOps provided overlays are composed of sub-overlays. Each Ping Identity Platform product has its own overlay. There are other overlays to handle shared pieces. You can apply or delete sub-overlay or the entire overlay using kubectl apply -k or kubectl delete -k commands.

Specify overlay or environment to target

With discrete overlays, you need to specify which overlay you want to target when running the forgeops commands. If you forget to specify the overlay, the command exits and lets you know to provide one. Only the apply and info commands allow you to not specify an overlay.

Helm Support

Both Kustomize and Helm are supported by the forgeops command. Use the forgeops env command to generate Helm values file and Kustomize overlays for existing environments. The forgeops build command updates the Helm values file and the Kustomize image-defaulter overlay file for the specified environment.

The forgeops command can generate the values.yaml file from an already deployed environment, it cannot generate the values.yaml file for a new environment.

The values.yaml file contains all the Helm values. While the values.yaml file contains all the Helm values for an environment, few more files are created each containing a group of interrelated values that can be copied and used in other environments, if you need to.

Setup

The forgeops command is developed using Python. Run the forgeops configure command to ensure the required packages are set up:

$ cd /path/to/forgeops/bin
$ ./forgeops configure

You need to run the forgeops configure once before creating and managing your ForgeOps deployment environments.

Workflow

The workflow of forgeops is designed to be production first and has three distinct steps:

1. Create an environment: This step is used to manage the overlay and values files on an ongoing basis. Only the requested changes are incorporated, so the customizations are not impacted.
2. Build images for the environment: The build step assembles the file-based configuration changes into container images, and updates the image-defaulter and values files for the targeted environment.
3. Apply the environment: In this step, you deploy the image you configured.

It is recommended that you start with a single-instance deployment to develop your AM and IDM configuration, so you can export them and build your custom container images.

1. Create an environment

You must create an environment first using the forgeops env command. You need to specify an FQDN (--fqdn) and an environment name (--env-name).

Previously, the t-shirt sized overlays called small, medium, and large were provided, along with the default overlay cdk. With forgeops, a single-instance overlay replaces cdk. The single-instance overlay is considered the default and is provided in the kustomize-ng/overlay/default directory.

You can use --small, --medium, and --large flags to configure your overlay, and the forgeops env command populates your environment with the size you requested.

For example, the following command creates a medium-sized stage deployment with an FQDN of stage.example.com:

$ cd /path/to/forgeops
$ ./bin/forgeops env --fqdn stage.example.com --medium --env-name stage

The default deployment size is single-instance. The following example command creates a single-instance environment:

$ cd /path/to/forgeops
$ ./bin/forgeops env --fqdn stage.example.com --env-name stage-single

You will find the generated Kustomize overlay files in the kustomize-ng/overlay/ENV-NAME folder. If you are modifying an existing Helm-based environment, then you will also find the Helm specific value files in the charts/identity-platform folder.

2. Build images for the environment

Use the forgeops build command to create a new container image for the environment you created in the Create an environment step. The forgeops build command applies the config profile from the build docker/am/config-profiles/profile and docker/idm/config-profiles/profile to build AM and IDM container images and push the images to your container registry. It also updates the image-defaulter and values files for the targeted environment.

To build new AM and IDM images for our stage environment using the stage-cfg profile, run the command:

$ ./bin/forgeops build --env-name stage \
 --config-profile stage-cfg \
 --push-to my.registry.com/my-repo/stage am idm

3. Apply the environment

Use the overlay you created in the Create an environment step and deploy the environment built in the Build images for the environment step.

Kustomize-based deployment

You have two options to perform ForgeOps deployment in a Kustomize-based environment:

Using the kubectl apply command, for example:

$ kubectl apply -k /path/to/forgops/kustomize-ng/overlay/my-overlay

Using the forgeops apply command, for example:
```
$ ./bin/forgeops apply --env-name stage
```

If you are using Helm-based deployment methods, you cannot use the forgeops command to perform ForgeOps deployment. Instead, use the helm install or helm upgrade command with the Helm values file:

$ helm upgrade --install ...

`forgeops` commands

The forgeops command is a Bash wrapper script that calls appropriate scripts in bin/commands. These scripts are written in either Bash or Python. All the bash scripts support the new --dryrun flag which display the command that would be run and enable you to inspect it before actually running the command. The Python scripts env and info do not support --dryrun.

Helm Support: Both Kustomize and Helm are supported by the forgeops command. Use the forgeops env command to generate Helm values files and Kustomize overlays for each environment. The forgeops build command updates the Helm values file and the Kustomize image-defaulter overlay file for the specified environment.

The values.yaml file contains all the Helm values. The other files group the different values so that you can use them individually if you need to.
Custom paths: By default, forgeops uses the docker, kustomize, and helm directories. You can set up your own locations separately and specify the appropriate flags on the command line or set the appropriate environment variable in the path/to/forgeops/forgeops.conf file.

Learn more about the forgeops command options in the forgeops command reference.

ForgeOps