forgeops command reference">

ForgeOps

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:

--amster-retain n

Keep the amster pod running for n seconds. The default is 10 seconds. Specify infinity to keep the amster pod running indefinitely.

--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 have not 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 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 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

forgeops env --env-name my-env --fqdn my-fqdn

Create, configure, and manage a ForgeOps deployment environment. This subcommand has no component specifications. This command lets you define the parameters for your deployment environment, such as FQDN, certificate issuer, and so on. By doing so, you don’t have to specify these parameters when using the other commands, such as forgeops apply, forgeops build, and so on.

--fqdn my-fqdn

A comma separated list of FQDNs. For example:

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

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 overlay.

Default: False.

--env-name my-env

Name of environment to manage.

Default: None.

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

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

1. Except for the deprecated amster component.