ForgeOps

Migrate your Kustomize configurations

This section covers steps required to migrate your Kustomize overlays from legacy ForgeOps artifacts, such as 7.4 or 7.5, to the new ForgeOps deployment environment.

  1. If you are using DS Operator in your deployment, then use step 3 in Upgrade from version 7.3 to migrate away from using the DS Operator and then perform the migration.

  2. When you migrate Kustomize overlays, don’t copy the files from the old overlay. Create a new overlay and then copy the content in the old overlay to the new overlay.

The format and layout of the overlays in the new main branch have changed from the previous ForgeOps releases. The main changes are:

  • Each overlay contains sub-overlays for each product. This enables users to deploy products individually or collectively just as with the previous version of the forgeops command.

  • The image-defaulter is included in the overlay, so that it’s specific for a deployment environment.

  • Each product has a separate dedicated ingress file. This enables users to set up product-specific configurations if required. Therefore, set up the FQDN for your new environment using the forgeops env command. Don’t migrate the old ingress overlay.

Considerations

Using the new forgeops command, you can select the version of products you want to deploy from 7.4 onwards. ForgeOps team recommends you migrate your deployment in the following way:

  1. Migrate your overlay to the new overlay layout using the steps below.

  2. Upgrade your images to a new version once your overlay is updated. Learn more at Migrate from a ForgeOps 7.4 or 7.5 release branch to the 2025.2 tag.

Migrating your Kustomize overlays

To migrate your Kustomize overlays from previous versions, you need either of:

  • Your custom overlay and the contents of kustomize/deploy/image-defaulter/kustomization.yaml, or

  • Your custom deployment environment directory you’ve used to create a dedicated image-defaulter for your environment using the --deploy-env option.

Steps:

  1. Ensure your custom overlay or custom deployment environment directory is saved locally so it’s accessible when you check out the 2025.2.1 tag.

  2. Check out the 2025.2.1 tag.

    $ cd /path/to/forgeops/
$ git checkout 2025.2.1

  3. Create a new overlay specifying your FQDN and the certificate issuer. Add the --deployment-size flag that most closely represents your old deployment.

    This adds the configuration into the Helm values file for you, so it’s easy to edit the Helm values to match your Kustomize environment.

    $ ./bin/forgeops env --env-name my-env --fqdn my-fqdn \
  --cluster-issuer my-cluster-issuer --deployment-size

    1. Specify your FQDN when creating a new custom overlay as it will populate the required manifests in the new overlay.

    2. If you want to use a specific issuer for your deployment environment instead of the ClusterIssuer, then replace the --cluster-issuer option with --issuer option appropriately.

  4. Using the forgeops env command incorporate the modifications you made in your previous ForgeOps deployment. The following example shows how to set up AM replicas to 3:

    $ ./bin/forgeops env --env-name my-env am-rep 3

Updating existing overlay.
Updating existing helm values.
...

    Note the value of am:replicas in the my-env/am/deployment.yml file:

    apiVersion: apps/v1
kind: Deployment
  name: am
    replicas: 3
    template:
      spec:
  \...

  5. Run the forgeops image command to update the image in your container repository.

    1. Select the upstream platform image version for your running deployment. For example in a 7.5.0 platform:

      $ ./bin/forgeops image --env-name my-env --release 7.5.0 platform

    2. Set your custom images. For example, let’s say the am image lines look like this in the kustomize/overlay/my-env/image-defaulter/kustomization.yaml file:

      name: am
  newName: us-docker.pkg.dev/MyProject/images/am
  newTag: 7.5.0
\...

      Then use the forgeops image command with tag value of the component to build and store the component image in your container repository. For example, to build image for AM:

      $ ./bin/forgeops image --env-name my-env \
  --image-repo us-docker.pkg.dev/MyProject/images --tag 7.5.0 am
      Other things to watch out for

      • Update the base/base.yaml file, and ensure to correctly specify the FQDN, AM_STORES_CTS_SERVERS, and AM_STORES_USER_SERVERS.

      • A separate ingress file exists for each product. The FQDN is populated in these files when you set up the deployment environment using the forgeops env command.