ForgeOps

forgeops command reference

forgeops — Manage Ping Identity Platform components in a Kubernetes cluster

Synopsis

forgeops subcommand options

Description

  • Use Kustomize 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 | -h

Display command usage information.

Subcommands

forgeops build

forgeops build components options

Build a custom Docker image for one or more Ping Identity Platform components, and update the image defaulter file.

For components, specify:

  • am, ds, idm, or ig, to build a custom Docker image for a single Ping Identity Platform component.[1]

  • More than one component, to build multiple Docker images by running a single forgeops build command. Separate multiple components with a space. For example, forgeops build am idm.

  • all, to build Docker images for all the Ping Identity Platform components[2] by running a single forgeops build command.

Options

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

--config-profile | -p configuration profile path

Path that contains the configuration for am, idm, or ig. The forgeops build command incorporates the configuration files located at 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

For more information, refer to Configuration profiles.

The default value for the --config-profile option is cdk:

  • The docker/ig/config-profiles/cdk directory contains a starter configuration that you can use when you begin customizing the ig Docker image.

  • The docker/am/config-profiles/cdk and docker/idm/config-profiles/cdk directories are intentionally empty. The base images for the customized am and idm Docker images already contain starter configurations, so a starter configuration in a configuration profile is not needed.

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.

--deploy-env environment

The deployment environment.

Deployment environments let you manage deployment manifests and image defaulters for multiple environments in a single forgeops repository clone.

By default, the forgeops build command updates the image defaulter in the kustomize/deploy directory.

When you specify a deployment environment, the forgeops build command updates the image defaulter in the kustomize/deploy-environment directory. For example, if you ran forgeops build --deploy-env production, the image defaulter in the kustomize/deploy-production/image-defaulter directory would be updated.

You must initialize new deployment environments before using them for the first time. Refer to Initialize deployment environments.

--push-to | -r registry

Docker registry to which the Docker image being built is pushed. Required unless you have 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 takes precedence.

--reset

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

--tag | -t tag

Tag to apply to the Docker image being built.

forgeops clean

forgeops clean

Remove Kustomize manifests for a Ping Identity Platform deployment from a forgeops repository clone.

The forgeops clean command removes Kustomize manifests from:

  • The kustomize/deploy directory, if you do not specify the --deploy-env option when you run the command.

  • The kustomize/deploy-environment directory, if you specify the --deploy-env option when you run the command.

Options

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

--deploy-env environment

Deployment environment to remove.

Specify this option if you specified a deployment environment when you ran the forgeops install or forgeops generate command. Note that by default, these two commands generate Kustomize manifests in the kustomize/deploy directory, but when you run them with the --deploy-env option, they generate the manifests in the kustomize/deploy-environment directory.

forgeops delete

forgeops delete components options

Delete Ping Identity Platform components or sets of components, PVCs, volume snapshots, and Kubernetes secrets from a running Kustomize-based ForgeOps deployment. Do not use the forgeops delete command with Helm-based ForgeOps deployments.

By default, the forgeops delete command prompts you to verify whether you want to delete Ping Identity Platform components, PVCs, volume snapshots, and Kubernetes secrets. You can modify the default behavior to suppress confirmation prompts as necessary.

For components, specify:

  • admin-ui, am, amster, ds-cts, ds-idrepo, end-user-ui, idm, ig, or login-ui, to delete a single Ping Identity Platform component.

  • secrets, to delete the Kubernetes secrets from the deployment.

  • A named set of components:

    • apps, to delete the am, amster, idm, and ig components.

    • base, to delete the dev-utils and platform-config configmaps, Kubernetes ingress resources, and Kubernetes secrets. Secrets generated by cert-manager are not deleted.

    • ds, to delete all the DS components.

    • ui, to delete the admin-ui, end-user-ui, and login-ui components.

  • all, to delete all the Ping Identity Platform components.

  • More than one component or set of components, to delete multiple Ping Identity Platform components by running a single forgeops delete command. Separate multiple components with a space. For example, forgeops delete ui am.

The default value for components is all.

Options

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

--debug

Display debug information when executing the command.

--force | -f

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 | -n namespace

The namespace from which to delete Ping Identity Platform components.

Defaults to the active namespace in your local Kubernetes context.

--yes | -y

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.

forgeops generate

forgeops generate components options

Generate Kustomize manifests for a Ping Identity Platform deployment.

By default, the forgeops generate command places manifests in the kustomize/deploy directory. You can alter this location by specifying a deployment environment.

The forgeops generate and forgeops install commands are similar, except that the forgeops generate command does not deploy Ping Identity Platform components after generating Kustomize manifests. If you generate manifests for Ping Identity Platform components by running the forgeops generate command, you can then deploy them by running kubectl apply -k commands. For more information, refer to the deployment documentation.

For components, specify:

  • admin-ui, am, amster, ds-cts, ds-idrepo, end-user-ui, idm, ig, or login-ui, to generate a manifest for a single Ping Identity Platform component.

  • secrets, to generate a manifest for Kubernetes secrets.

  • A named set of components:

    • apps, to generate a manifest for the am, amster, idm, and ig components.

    • base, to generate a manifest for the dev-utils and platform-config configmaps, Kubernetes ingress resources, and another manifest for Kubernetes secrets.

    • ds, to generate a manifest for all the DS components.

    • ui, to generate a manifest for the admin-ui, end-user-ui, and login-ui components.

  • all, to generate manifests for all the Ping Identity Platform components.

  • More than one component or set of components, to generate manifests for multiple Ping Identity Platform components by running a single forgeops generate command. Separate multiple components with a space. For example, forgeops generate ui am.

The default value for components is all.

Options

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

--cdk | --custom overlay path | --large | --medium | --mini | --small

Deployment size. References a Kustomize overlay that contains YAML patch files that alter the behavior of the related base Kustomize files. Kustomize overlays provided by ForgeRock reside in the kustomize/overlay directory. Base Kustomize files reside in the kustomize/base directory.

If none of these options are specified, the deployment size option defaults to --cdk.

Refer to ForgeOps architecture for information about deployment sizing and contents options for ForgeOps deployments.

About the --custom option:

Specify the --custom option if you want to provide your own overlay that specifies Kubernetes deployment environment characteristics rather than using one of the deployment sizes provided by ForgeRock. For overlay path, specify the full path where the patch files are located.

The names of the patch files residing in overlay path must align with the names expected by the forgeops generate command:

  • am.yaml for the am, apps, and all components

  • idm.yaml for the idm, apps, and all components

  • ig.yaml for the ig and all components

  • ingress.yaml and/or secret_agent_config.yaml for the base and all components

--debug

Display debug information when executing the command.

--deploy-env environment

The deployment environment.

Deployment environments let you manage deployment manifests and image defaulters for multiple environments in a single forgeops repository clone.

By default, the forgeops generate command generates Kustomize manifests in the kustomize/deploy directory.

When you specify a deployment environment, the forgeops generate command generates the manifests in the kustomize/deploy-environment directory. For example, if you ran forgeops generate --deploy-env production, Kustomize manifests would be placed in the kustomize/deploy-production directory.

You must initialize new deployment environments before using them for the first time. Refer to Initialize deployment environments.

--fqdn | -n fqdn

The fully-qualified hostname to use in the deployment.

Defaults to namespace.iam.example.com, where namespace is the active namespace in your local Kubernetes context.

Relevant only for the forgeops generate all and forgeops generate base commands; ignored for other forgeops generate commands.

--ingress-class | -i

The type of ingress controller used in the deployment.

Possible values are nginx and haproxy. The default value is nginx.

Relevant only for the forgeops generate all and forgeops generate base commands; ignored for other forgeops generate commands.

--operator | -o

Generate artifacts needed for deployment with the DS operator.

Use this option only if your deployments use the deprecated DS operator.

forgeops info

forgeops info options

Write administrative passwords and URLs for accessing Ping Identity Platform admin UIs to standard output.

Options

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

--debug

Display debug information when executing the command.

--json

Display output in JSON format.

--namespace | -n namespace

The namespace that contains Ping Identity Platform components.

Defaults to the active namespace in your local Kubernetes context.

forgeops install

forgeops install components options

Generate Kustomize manifests for a Ping Identity Platform deployment, and then deploy the components in a Kubernetes cluster.

By default, the forgeops install command places manifests in the kustomize/deploy directory. You can alter this location by specifying a deployment environment.

The forgeops generate and forgeops install commands are similar, except that the forgeops generate command does not deploy Ping Identity Platform components.

For components, specify:

  • admin-ui, am, amster, ds-cts, ds-idrepo, end-user-ui, idm, ig, or login-ui, to deploy a single Ping Identity Platform component.

  • secrets, to deploy Kubernetes secrets. Secrets generated by cert-manager are not deployed.

  • A named set of components:

    • apps, to deploy the am, amster, idm, and ig components.

    • base, to deploy the dev-utils and platform-config configmaps, Kubernetes ingress resources, and Kubernetes secrets. Secrets generated by cert-manager are not deployed.

    • ds, to deploy all the DS components.

    • ui, to deploy the admin-ui, end-user-ui, and login-ui components.

  • all, to deploy all the Ping Identity Platform components.

  • More than one component or set of components, to deploy multiple Ping Identity Platform components by running a single forgeops install command. Separate multiple components with a space. For example, forgeops install ui am.

The default value for components is all.

Options

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

--amster-retain | -a seconds

Amount of time, in seconds, to leave the Amster pod up and running after the Amster job to restore dynamic configuration finishes.

Specify either a number of seconds to retain the Amster pod, or infinity if you want the pod to run indefinitely. The default value is 10.

--cdk | --custom overlay path | --large | --medium | --mini | --small

Deployment size. References a Kustomize overlay that contains YAML patch files that alter the behavior of the related base Kustomize files. Kustomize overlays provided by ForgeRock reside in the kustomize/overlay directory. Base Kustomize files reside in the kustomize/base directory.

If none of these options are specified, the deployment size option defaults to --cdk.

Refer to ForgeOps architecture for information about deployment sizing and contents options for ForgeOps deployments.

About the --custom option:

Specify the --custom option if you want to provide your own overlay that specifies Kubernetes deployment environment characteristics rather than using one of the deployment sizes provided by ForgeRock. For overlay path, specify the full path where the patch files are located.

The names of the patch files residing in overlay path must align with the names expected by the forgeops install command:

  • am.yaml for the am, apps, and all components

  • idm.yaml for the idm, apps, and all components

  • ig.yaml for the ig and all components

  • ingress.yaml and/or secret_agent_config.yaml for the base and all components

--debug

Display debug information when executing the command.

--deploy-env environment

The deployment environment.

Deployment environments let you manage deployment manifests and image defaulters for multiple environments in a single forgeops repository clone.

By default, the forgeops install command generates Kustomize manifests in the kustomize/deploy directory and runs Docker images defined in the image defaulter in the kustomize/deploy/image-defaulter directory.

When you specify a deployment environment, the forgeops install command generates the manifests in the kustomize/deploy-environment directory. For example, if you ran forgeops generate --deploy-env production, Kustomize manifests would be placed in the kustomize/deploy-production directory.

It then runs Docker images specified in the environment’s image defaulter, located in the kustomize/deploy-production/image-defaulter directory.

You must initialize new deployment environments before using them for the first time. Refer to Initialize deployment environments.

--fqdn | -n fqdn

The fully-qualified hostname to use in the deployment.

Defaults to namespace.iam.example.com, where namespace is the active namespace in your local Kubernetes context.

Relevant only for the forgeops install all and forgeops install base commands; ignored for other forgeops install commands.

--ingress-class | -i

The type of ingress controller used in the deployment.

Possible values are nginx and haproxy. The default value is nginx.

Relevant only for the forgeops install all and forgeops install base commands; ignored for other forgeops install commands.

--operator | -o

Install DS pods using the DS operator.

If you specify this option, the forgeops install command determines whether you have deployed the DS operator. If you haven’t deployed the operator, the forgeops install command deploys it before attempting to install DS pods.

Use this option only if your deployments use the deprecated DS operator.

--timeout | -t seconds

The maximum number of seconds to pause before terminating the forgeops install command if an intermediate process does not complete.

The default value for the --timeout option is 600.

forgeops wait

forgeops wait component options

Wait for Ping Identity Platform components to fully start up.

Use the forgeops wait command to pause further execution until a Ping Identity Platform component is fully deployed. For example:

  • When deploying components using a technique other than the forgeops install command, such as deploying Kustomize manifests by using the kubectl apply -k command.

  • When deploying components in one shell while performing another operation that depends on deployment completion in another shell.

Because the forgeops install command waits for completion of component deployment before proceeding, it is generally not necessary to use the forgeops wait command when you deploy the platform by using the forgeops install command.

For component, specify:

  • am, amster, ds-cts, ds-idrepo, idm, ig, to wait for a single Ping Identity Platform component to be deployed.

  • A named set of components:

    • apps, to wait for the am, amster, idm, and ig components to be deployed.

    • ds, to wait for all the DS components to be deployed.

You must specify a single component or set of components as an argument to the forgeops wait command. You cannot specify multiple components, and there is no default component.

Options

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

--debug

Display debug information when executing the command.

--namespace | -n namespace

The namespace that contains Ping Identity Platform components.

Defaults to the active namespace in your local Kubernetes context.

--timeout | -t seconds

The maximum number of seconds to pause before terminating the forgeops wait command.

The default value for the --timeout option is 600.

1. Building a Docker image for the amster component is deprecated.
2. Except for the deprecated amster component.