IBM Support

Part 3: GitOps Advanced Configuration

White Papers


Abstract

This tutorial series explains advanced configuration of the GitOps object, which includes automatic interval reads and selection of the same size template policies for different DataPower environments. In the first two parts, you learned how to configure GitOps and GitOps Template objects to perform basic Reads and Writes with template replacement. In Part 3, you learn how to define template policies and GitOps modes. This configuration allows for enforcement of source creation as well as transformation of variable fields such as IP addresses and ports for specific environmental requirements.

Content

Introduction

DataPower service development and configuration maintenance are generally intensive manual operations. The user must log in to an interface (for example UI or CLI), and make changes. There is no out of the box tooling to automate configuration changes across several DataPower appliances. GitOps integration provides versioning and propagation of configuration changes with environment-specific configuration through templating.

GitOps operation modes

In version 10.6.0, two types of operation modes exist: read-only and read/write.

  • Read-only mode: In read-only mode, you can perform only GitOps read operations. This mode is typically configured on a device where new configuration is only consumed. Optionally, when read-only mode is set, an interval can be configured. This interval represents a length between polls to perform a GitOps read operation automatically.
  • Read/write mode: In read/write mode, you can perform both GitOps read and GitOps write operations. This mode is typically configured on a device that is both committing and consuming new configuration.

GitOps template policies

Within the GitOps object, a vector of template policies can be configured. The vector represents the name of the template objects to be retrieved before a GitOps read operation is performed. The template sets must be equal between the template policies on the GitOps object and the templated values on the domain's source JSON. In other words, if every IP and port in a domain's source JSON are templated values, the GitOps object must have entries in the template policy vector that resolves all IP and port template values.

Full GitOps example with multiple environments

In this example, a MultiProtocolGateway named Sample_MPGW exists.

Two environments exist, Development and Production, each with the Sample_Router domain. On each environment's Sample_Router domain, a GitOps object is configured.

In the Development environment, the GitOps object is configured as follows

gitops
  admin-state enabled
  type https
  mode read-write
  commit-id-type branch
  commit-id "dev_branch"
  location "https://github.sample.com/bwgarnet/sample-gitops.git"
  username "bwgarnet"
  password brentPAT
  name "Brent G"
  email "bwgarnet@sample.com"
  template-policy "DevelopmentAddresses"
exit

Note:

  • The GitOps object is configured in read/write mode.
  • The Commit-ID is set to the dev_branch branch.
  • The template policy vector has one entry that specifies to sync and use the DevelopmentAddresses template policy.

In the Production environment, the GitOps object is configured as follows.

gitops
  admin-state enabled
  type https
  mode read-only
  interval 60
  commit-id-type branch
  commit-id "main"
  location "https://github.sample.com/bwgarnet/sample-gitops.git"
  username "bwgarnet"
  password brentPAT
  name "Brent G"
  email "bwgarnet@sample.com"
  template-policy "ProductionAddresses"
exit

Note:

  • The GitOps object is configured in read-only mode.
  • The Commit-ID is set to the main branch.
  • The interval is set to check for sync every 60 minutes.
  • The template policy vector has one entry that specifies to sync and use the ProductionAddresses template policy.

On the Git repository, a Sample_Router domain is configured. This domain contains a MultiProtocolGateway named Sample_MPGW and all supporting service configuration. In addition to the domain configuration, a templates directory is automatically created when a GitOps write template action is performed. Supporting templates ProductionAddresses and DevelopmentAddresses exist in the templates directory. These templates contain an equal set that resolves template values for both the HTTPSourceProtocolHandler Port field and the MultiProtocolGateway BackendURL field.

On the Git repository, the template config JSON is as follows.

/datapower/templates/ProductionAddresses.cfg.json /datapower/templates/DevelopmentAddresses.cfg.json 
{
  "GitOpsTemplate":{
    "@name":"ProductionAddresses",
    "mAdminState":"enabled",
    "Templates":[
      {
        "TemplateType":"change",
        "ClassName":"MultiProtocolGateway",
        "Name":"Sample_MPGW",
        "Field":"BackendURL",
        "Value":"https://prod.sample.com:443",
        "ValueInverse":null,
        "ValueValidate":null
      },
      {
        "TemplateType":"change",
        "ClassName":"HTTPSourceProtocolHandler",
        "Name":"Sample_FSH",
        "Field":"LocalPort",
        "Value":"80",
        "ValueInverse":null,
        "ValueValidate":null
      }
    ]
  }
}
 
{
  "GitOpsTemplate":{
    "@name":"DevelopmentAddresses",
    "mAdminState":"enabled",
    "Templates":[
      {
        "TemplateType":"change",
        "ClassName":"MultiProtocolGateway",
        "Name":"Sample_MPGW",
        "Field":"BackendURL",
        "Value":"https://dev.sample.com:4433",
        "ValueInverse":null,
        "ValueValidate":null
      },
      {
        "TemplateType":"change",
        "ClassName":"HTTPSourceProtocolHandler",
        "Name":"Sample_FSH",
        "Field":"LocalPort",
        "Value":"8080",
        "ValueInverse":null,
        "ValueValidate":null
      }
    ]
  }
}

Note:

  • Two template files exist which both contain the same set of fields to resolve.
  • The template files differ in values that specify how to resolve environment-specific values.
  • On the domain's source, no values exist for HTTPSourceProtocolHandler Port field and the MultiProtocolGateway BackendURL field, rather template values of the form {{ change_classname_name_field }} are displayed as template placeholders.

On the development device, a GitOps Read can be performed to synchronize the domain and the template DevelopmentAddresses to dev_branch HEAD. The result of the operation is persisted domain configuration on the device with changes to HTTPSourceProtocolHandler Port field and the MultiProtocolGateway BackendURL field. The values of each respective field are specified by the DevelopmentAddresses template. After GitOps read the domain's configuration is at HEAD with the specified branch, and the developer can make new development changes.

In this example, Sample_MPGW BackTimeout is reduced from 120 seconds to 60 seconds. Performing a GitOps write replaces the domain's JSON, templating the fields specified in DevelopmentAddresses while also updating the new BackTimeout of 60 seconds.

On the Git repository, the dev_branch now has an updated domain JSON as follows.

/datapower/config/Sample_Router/Sample_Router.cfg.json 
{
  "@build":"rel-10-5-3-branch",
  "@timestamp":"Wed Nov 01 12:00:00 2023",
  "configuration":[
    {
      "MultiProtocolGateway":{
        "@name":"Sample_MPGW",
        "mAdminState":"enabled",
        "Priority":"normal",
        "FrontProtocol":[
          "Sample_FSH"
        ],
        "FrontTimeout":120,
        "BackTimeout": 60,
        "Type":"dynamic-backend",
        "BackendURL" : "{{ change_MultiProtocolGateway_Sample_MPGW_BackendURL }}"
        . . .
      }
    },
    {
      "HTTPSourceProtocolHandler":{
        "@name":"Sample_FSH",
        "mAdminState":"enabled",
        "LocalAddress":"0.0.0.0",
        "LocalPort": "{{ change_HTTPSourceProtocolHandler_Sample_FSH_LocalPort }}",
        . . .
      }
    }
    . . .
  ]
}

To promote the changes to any Read-Only consumers, a merge on the Git repository is performed by a manual or pipeline process. The change on dev_branch is accepted and merged to the main branch.

On the production device, the automatic GitOps Read occurs on the specified interval. After GitOps Read the domain configuration is at main HEAD, resolving templated values by using the ProductionAddresses template profile. The HTTPSourceProtocolHandler Port field and the MultiProtocolGateway BackendURL field values are replaced as specified by the ProductionAddresses template and the new BackTimeout of 60 seconds is applied.

On the production device the configuration, represented as JSON, is as follows.

{
  "@build":"rel-10-5-3-branch",
  "@timestamp":"Wed Nov 31 12:00:00 2023",
  "configuration":[
    {
      "MultiProtocolGateway":{
        "@name":"Sample_MPGW",
        "mAdminState":"enabled",
        "Priority":"normal",
        "FrontProtocol":[
          "Sample_FSH"
        ],
        "FrontTimeout":120,
        "BackTimeout":60,
        "Type":"dynamic-backend",
        "BackendURL" : "https://prod.sample.com:443"
        . . .
      }
    },
    {
      "HTTPSourceProtocolHandler":{
        "@name":"Sample_FSH",
        "mAdminState":"enabled",
        "LocalAddress":"0.0.0.0",
        "LocalPort": "80",
        . . .
      }
    }
    . . .
  ]
}

[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SS9H2Y","label":"IBM DataPower Gateway"},"ARM Category":[{"code":"a8m50000000L0rqAAC","label":"DataPower"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"10.5.3"}]

Document Information

More support for:
IBM DataPower Gateway

Component:
DataPower

Software version:
10.5.3

Document number:
7085898

Modified date:
13 June 2024

UID

ibm17085898

Manage My Notification Subscriptions

Page Feedback