ForgeOps

Migrate your Kustomize overlay content

This section covers steps required to migrate your Kustomize overlays from your 7.4 or 7.5 forgeops release branch to overlays in 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.1.x tag.

Steps to migrate your overlay

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 have 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 is accessible when you check out the 2025.1.2 tag.

  2. Check out the 2025.1.2 tag.

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

  3. Create a new custom overlay specifying your FQDN and the certificate issuer.

    $ ./bin/forgeops env --e my-env --fqdn my-fqdn --cluster-issuer my-cluster-issuer

    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. Copy the patch information from the previous custom overlay patch files or your deployment directory to the new overlay files.

    For example:

    • Old overlay: From old-overlay/am.yaml to new-overlay/am/deployment.yaml

    • Environment directory: From deploy-custom/apps/am.yaml to new-overlay/am/deployment.yaml

If you need to include additional patches, add them in to the corresponding sub-overlay and update the corresponding kustomization.yaml file to include them. The new forgeops command applies the overlays correctly during ForgeOps deployment unlike the forgeops command in previous releases that ignored kustomization.yaml.

Other things to watch out for

  • Update the base/base.yaml file, and ensure that the FQDN is specified correctly.

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

  • Update your image-defaulter/kustomization.yaml in the new overlay with image URLs and images tags from your old deploy/image-defaulter/kustomization.yaml or your custom my-env/image-defaulter/kustomization.yaml.