forgeops command reference

forgeops — The new generation utility simplifies deploying and managing Ping Identity Platform components in a Kubernetes cluster. You can create and manage custom Kustomize overlays and Helm value files for each deployment. You can then apply the customized overlays or value files using Kustomize or Helm appropriately.

The forgeops command reference documentation is currently in developmental preview stage, and not all command options have been documented yet. To get help in the command-line interface, use the forgeops --help command.

Synopsis

forgeops subcommand options

Description

Generate custom component overlays and value files.
Use Kustomize or Helm to install Ping Identity Platform components in a Kubernetes cluster.
Delete platform components from a Kubernetes cluster.
Build custom Docker images for the Ping Identity Platform.

Options

The forgeops command takes the following option:

--help: Display command usage information.

The following subcommands clean, config, install, and generate have been deprecated because their functionality is provided through other existing subcommands.

Subcommands

forgeops apply

forgeops apply components options

Runs the kubectl apply -k command to apply Ping Identity Platform Kustomize overlay from the specified overlay directory into a Kubernetes namespace. If the specified overlay directory doesn’t exist, a new one is created.

The forgeops apply subcommand subsumes all the functionality of forgeops install. Accordingly, forgeops install is deprecated.

For components, specify:

am, amster, ds-cts, ds-idrepo, idm, or ig to deploy each Ping Identity Platform component.
More than one component or set of components separated by a space to deploy multiple Ping Identity Platform components. For example, forgeops apply ds-idrepo ds-cts am.
secrets to deploy Kubernetes secrets. Secrets generated by cert-manager are not deployed.
base to deploy the platform-config configmap Kubernetes ingress resources and Kubernetes secrets. Secrets generated by cert-manager are not deployed.
all to deploy all the Ping Identity Platform components.

The default value for components is all.

Options

The forgeops apply subcommand takes the following options:

--create-namespace

Create a namespace if it doesn’t exist. The default is the current namespace of the user.

--debug

Display debug information when executing the command.

--dryrun

To perform a dry run without actually applying or installing the components.

--env-name my-env

Name of environment to apply. The default is demo.

--fqdn my-fqdn

The fully qualified hostname to use in the deployment.

The namespace specified in the forgeops env command is used by default. For simple demo purposes, the namespace specified in the default overlay file is used.
Relevant only for the forgeops apply all and forgeops apply base commands. This option is ignored for other forgeops apply commands.

--namespace ns

The namespace in which to install the ForgeOps platform components. If you need to create the namespace, then specify the --create-namespace | -c option.

--kustomize my-kustomize-path

The directory that contains Kustomize overlays. Specify the full path to the directory or the path relative to the base of your local forgeops repository. The default value is kustomize.

Examples

Use an environment my-env: forgeops apply --env-name my-env
Do a dry run: forgeops apply --dryrun --env-name my-env

forgeops build

forgeops build --env-name my_env components options

Use the forgeops build command to build custom Docker images for one or more Ping Identity Platform components, and update the Helm values file and the Kustomize image-defaulter overlay file for the specified environment.

Building an amster image is not supported, so use bin/forgeops amster.
The --config-profile option is applicable only for AM, idm_abbr, and PingGateway.
Use the --push-to option or set the PUSH_TO variable in your environment.
Use the --push-to none option for building local images in minikube.

For components, specify:

am, ds, idm, or ig to build a custom Docker image for a single Ping Identity Platform component.
More than one component or set of components separated by a space to build multiple Docker images in a single forgeops build command. For example, forgeops build --env-name [.var]#my-env am idm#.
all to build Docker images for all the Ping Identity Platform components^[1] by running a single forgeops build command.

Options

In addition to the global forgeops command options, the forgeops build subcommand takes the following options:

--build-path path

The directory path where the build images are to be located. By default, the images are placed in path/to/forgeops/docker.

--config-profile config-profile-path

Path that contains the configuration for am, idm, or ig. The forgeops build command incorporates the configuration files located in this path in the custom Docker image it builds.

Configuration profiles reside in subdirectories of one of these paths in a forgeops repository clone:

docker/am/config-profiles
docker/idm/config-profiles
docker/ig/config-profiles

Learn more in Configuration profiles.

Customized ds images do not use configuration profiles. To customize the ds image, add customizations to the docker/ds directory before running the forgeops build ds command.

--debug

Display debug information when executing the command.

--dryrun

To perform a dry run without actually building the component images.

--env-name my-env

The name of the deployment environment that is used for building or deploying the image. Deployment environments let you manage deployment manifests and image defaulters.

You must initialize new deployment environments before using them for the first time. You must specify the --env-name option in the forgeops build command if you haven’t set up the ENV_NAME shell environment variable.

The forgeops build command updates the image defaulter in the target environment. For example, if you ran forgeops build --env-name prod, the image defaulter in the kustomize/overlay/deploy-prod/image-defaulter directory would be updated.

--kustomize

The path to the directory where the Kustomize overlays and the image defaulter files for the environment are located. You can specify the full path or path relative to the local directory of your forgeops repository clone.

--push-to registry

Docker registry where the Docker image being built is pushed. You must specify the push-to option unless you’ve set the PUSH_TO environment variable.

For deployments on minikube, specify --push-to none to push the Docker image to the Docker instance running within minikube.

If you specify both the --push-to option and the PUSH_TO environment variable, the value of the --push-to option takes precedence.

--reset

Revert all the tags and new image names in the image defaulter file to their last committed values.

--tag my-tag

Tag to apply to the Docker image being built.

Examples

Normal operation: forgeops build --config-profile prod --env-name prod --tag prod-am-123 am
Do a dry run: forgeops build --config-profile prod --env-name prod --dryrun am

forgeops delete

forgeops delete --env-name my-env <components> <options>

Delete Ping Identity Platform components or sets of components, PVCs, volume snapshots, and Kubernetes secrets from a running Kustomize-based ForgeOps deployment.

By default, the forgeops delete command prompts you to confirm if you want to delete PVCs, volume snapshots, and Kubernetes secrets. You can suppress confirmation prompts as necessary by using the --yes option. For example, forgeops delete --env-name test --yes, deletes all Ping Identity Platform components in the test environment.

For components, specify:

am, ds-cts, ds-idrepo, idm, or ig to delete a single Ping Identity Platform component.
secrets to delete the Kubernetes secrets from the deployment.
- base to delete the platform-config configmap, Kubernetes ingress resources, and Kubernetes secrets. Secrets generated by cert-manager are not deleted.
all to delete all the Ping Identity Platform components.
More than one component or set of components separated by a space to delete multiple Ping Identity Platform components. For example, forgeops delete --env-name my-env am idm.

The default value for components is all.

Options

The forgeops delete subcommand takes the following options:

--debug: Display debug information when executing the command.
--dryrun: To perform a dry run without actually deleting the components.
--env-name my-env: The name of the deployment environment that contains the Kustomization overlays. You must specify the --env-name option, otherwise the forgeops delete command fails to run.
--force: When deleting Ping Identity Platform components, also delete PVCs, volume snapshots, and Kubernetes secrets.

When you specify this option, you still receive the OK to delete components? confirmation prompt. Specify the --yes option together with --force to suppress this confirmation prompt.
--namespace my-namespace: The namespace from which to delete Ping Identity Platform components.

Defaults to the active namespace in your local Kubernetes context.
--yes: Suppress all confirmation prompts.

When you specify this option, PVCs, volume snapshots, and Kubernetes secrets are not deleted. Specify the --force option together with --yes to delete PVCs, volume snapshots, and Kubernetes secrets.

Examples

Normal operation: forgeops delete --env-name prod am
Do a dry run: forgeops delete --env-name prod am --dryrun

forgeops env

The forgeops env command enables you to set up a ForgeOps deployment environment with parameters such as FQDN, ingress, and secret management tool.

Command details

forgeops env --env-name my-env OPTION

Create, configure, and manage a ForgeOps deployment environment. This command lets you define the parameters for your deployment environment, such as FQDN, certificate issuer, and so on by configuring:

Kustomize overlay files for each component in the /path/to/forgeops/kustomize/overlay/my-env directory.
A Helm values file in the /path/to/forgeops/helm/my-env directory.

By unifying the parameters in a location, you don’t have to specify these parameters when using the other commands, such as forgeops apply, forgeops build, and so on.

Options

--amster-retain n: Keep the amster pod running for n seconds. The default is 10 seconds.
--fqdn my-fqdn: A comma separated list of FQDNs. For example:

forgeops env --env-name my-env --fqdn my-fqdn1, my-fqdn2

This is a mandatory parameter. Default: None.
--helm path/to/helm/directory: The directory where Helm values files are located. The directory path can be relative to the forgeops root directory or an absolute path.
--ingress my-ingress: Ingress class name.

Default: None.
--kustomize my/kustomize: The directory that contains Kustomize overlays. The directory path can be an absolute or relative to the forgeops root directory.
--namespace my-namespace: The Kubernetes namespace where the Ping Identity Platform components are deployed.

Default: None.
--no-namespace: Remove namespace from Kustomize overlay.

Default: False.
--env-name my-env: Name of environment to manage.

Default: None.
--secret-agent: To enable the secret agent as the secret management utility.

Default: --secret-agent is enabled.
--secret-generator: To enable the secret generator as the secret management utility instead of the default secret agent.
--single-instance: To use a single-instance configuration. In a minikube environment, you must use the single-instance configuration option.

Default: False.
--source my-kust-source: Name of the source Kustomize overlay.

Default: None.
--ssl-secretname my-ssl-secret: Name of the secret containing private SSL data.

Default: None
--am-cpu, --am-mem, --am-rep: Specify the CPU, memory, and the number of AM pod replicas.
--cts-cpu, --cts-disk, --cts-mem, --cts-rep, --cts-snap-enable: Specify CPU, disk size, memory, replicas, and volume snapshots for ds-cts pods.
--idm-cpu --idm-mem --idm-rep: Specify the CPU, memory, and the number of IDM pod replicas.
--idrepo-cpu, --idrepo-disk, --idrepo-mem, --idrepo-rep, --idrepo-snap-enable: Specify CPU, disk size, memory, replicas, and enable volume snapshots for ds-idrepo pods.
--pull-policy my-pull-policy: Set policy for all platform images.
--no-helm: Don’t create or manage Helm values files.

Default: False.
--no-kustomize: Don’t create or manage Kustomize overlay.

Default: False.
--small, --medium, or --large: The size of ForgeOps deployment used in the environment.

Default: None.
--issuer my-issuer: The TLS certificate issuer within the namespace where the ForgeOps components are to be deployed.

Default: None.
--cluster-issuer my-cluster-issuer: The TLS certificate issuer that is available across the Kubernetes cluster where ForgeOps components are to be deployed. For demo purposes, you can use the certificate sample certificate issuer provided with ForgeOps, by using the --cluster-issuer default-issuer.

Default: None.
--skip-issuer: Skip TLS certificate issuer setup. If you use the --skip-issuer option when you set up a ForgeOps deployment environment, you must set up your TLS certificate issuer before performing a ForgeOps deployment.

Default: False.

forgeops image

The forgeops image command enables you to maintain ForgeOps deployments with the latest images available. Also, you can work with multiple versions of ForgeOps-provided images, providing more flexibility to upgrade the forgeops tool and ForgeOps deployment.

This feature is supported for ForgeOps version 7.4 and later.

Advantages

You can upgrade forgeops command and ForgeOps deployment separately on your schedule.
When upgrading, you can create a new release and test it through your different ForgeOps deployment environments.
Manage a single Git release branch instead of separate branches for each platform version.
You can use supported container images that are regularly scanned for OS-level security vulnerabilities.

Command details

forgeops image --env-name my-env my-components

Replace my-components with one or more of platform, apps, ui, am, amster, idm, ds, admin-ui, end-user-ui, login-ui, ig.

Options

--kustomize-path my-kustomize-loc

The absolute path or the path relative to the forgeops directory where Kustomize overlay files are stored.

Default: kustomize

--build-path my-docker-loc

The absolute path or the path relative to the forgeops directory where Docker files are stored.

Default: docker

--helm-path my-helm-loc

The absolute path or the path relative to the forgeops directory where Helm values files are stored.

Default: helm

--env-name my-env

Name of ForgeOps deployment environment in which you intend to manage Docker images.

--source my-src-env

Name of source environment if you are copying images.

--tag my-tag

Set the tag used for images.

--no-helm

Don’t manage Helm values files.

--no-kustomize

Don’t manage Kustomize overlay.

--copy

Copy images from --source to --env-name.

--release platform-release

Specify platform image release to set, for example 7.5.1.

--release-name my-release

Name of the release file in docker/component/releases. Default: my-release in UTC format.

--releases-src my-release-source-url

URL or path where release files live (default: http://releases.forgeops.com)

--image-repo my-docker-repo

The URL to the container registry that contains Docker images.

Short form	Default URL
base	us-docker.pkg.dev/forgeops-public/images-base
deploy	us-docker.pkg.dev/forgeops-public/images
dev	gcr.io/forgerock-io

Short form

Default URL

base

us-docker.pkg.dev/forgeops-public/images-base

deploy

us-docker.pkg.dev/forgeops-public/images

dev

gcr.io/forgerock-io

Learn more about the forgeops image command in Managing Ping Identity Platform images.

forgeops prereqs

The forgeops prereqs installs or upgrades prerequisites such as certificate manager, ingress, or secrets for deploying ForgeOps. This command replaces the install-prereqs script used in earlier ForgeOps releases.

Command details

forgeops prereqs prereqs

Options

--debug: Turn on debugging.
--dryrun: Do a dry run to validate the command without making any changes.
--verbose: Get detailed messages when running the command.
— haproxy: Use HAProxy instead of nginx ingress controller.
--secret-generator: Use the secret generator instead of the secret agent to manage secrets in the ForgeOps deployment. The secret generator must be already installed in the cluster.
--upgrade: Upgrade if the prerequite has been installed.

Examples

Install all prerequisites with defaults:

forgeops prereqs
Install HAProxy and the secret generator:

forgeops prereqs ingress --haproxy secrets --secret-generator
Install only cert-manager and secret-agent:

forgeops prereqs cert-manager secrets
Install only cert-manager and nginx:

forgeops prereqs cert-manager ingress
Install HAProxy:

forgeops prereqs ingress --haproxy

1. Except for the deprecated amster component.