A gwd_extension is one of the supported API Gateway extension types in a manifest extension.  Introduced in 10.5.0.5 and 10.5.4, the purpose of this type of extension is to allow customers to configure/customize objects created by the API Connect Gateway Service in ways that are not exposed through the API Manager.  Prior to the availability of this type of extension, customers had to use cfg script files in a filestore extension type to apply any customizations they wanted.  This required knowing the DataPower naming convention for objects and constant updates to cfg files to include new objects they create.  For example, if a customer wanted to add a default rate limit to all collections this would have previously required updating the extension every time a new catalog was created on APIM.  The user would have also needed to know the naming convention used on DataPower for collections to properly write the filestore extension.   Now with the gwd_extension type, new object instances can automatically inherit the customization(s). For the custom catalog rate limit, this could be done with a single override at a global scope so that it automatically applies the desired default rate limit to all catalogs.  The gwd_extension type also removes the need to know the DataPower naming convention for objects, instead users can now use the same names they use on the API Manager.

gwd_extension details:

• The gwd_extension is a single JSON map that contains all desired customizations the customer would like to make to almost any object created by the API Connect Gateway Service.
  • Objects not covered as of this blog
    • password alias's
    • certificate objects
      • Starting in 10.6.3.0, 10.6.0.5, 10.5.0.17, you can control the ignore expiration date properties of certificate objects
    • key objects
      
      
• The gwd_extension is a singleton, meaning only one gwd_extension can be defined in the manifest.json file.
  
  
• Customizations are an array of cli commands to be applied to the object before it is committed.
  • This does require knowledge of how to configure these objects on a DataPower in the cli or a cfg script. 
    • Knowledge center for cli commands
      
      
• Customizations can be defined at different scopes. 
  • _global:  At this scope all objects of a type created in a registered service will get the customizations
    • _instance: The global instance scope will apply the customizations to all objects of a type created in the registered service that match a criteria
  • _organization: At this scope all objects of a type created in a organization will get the customizations
    • _instance: The organization instance scope will apply the customizations to all objects of a type created in a provider organization that match a criteria
  • _catalog: At this scope all objects of a type created in a catalog with in a specific provider organization will get the customizations
    • _instance: The catalog instance scope will apply the customizations to all objects of a type created in a catalog of specific provider organization that match a criteria
  • _product: At this scope all objects of a type created in a product with in a catalog of a specific provider organization will get the customizations
  • _instance: At this scope only one specific object instance of a type created in a catalog with in a specific provider organization will get the customizations
    
    
• More than one scope can be defined for objects
  • Applied in order of impact: 
    • Global -> Global Instance -> Organization .-> Organization Instance -> Catalog -> Catalog Instance -> Product -> Product Instance -> Instance
      • For example:
        • Customers could define a global scope assembly rate limit that will be applied to all catalogs, 
        • Another assembly rate limit to be applied to all catalogs in a specific organization.
          • All catalogs in this organization would get the global scope and the organization scoped rate limit(s)
        • Another assembly rate limit that is only applied to a specific catalog in a specific organization.
          • This catalog scope would then get the global scoped rate limit(s)
          •  if it was a child of the organization scope then it would also get the organization scoped rate limit(s).  If it was in a different organization then it would not get those rate limits.  So from the map below it would get my-org limits but not my-other-org limits
          • It would then also get the rate limits defined at the catalog scope
        • Example Map:
          

          { 
            "api-collection":{
                "_global":{
                   "collection":[
                      "assembly-rate-limit ratelimit-global 10000 5 second on on on off off off \"\" \"1\""
                   ]
                },
                "_organization": {
                   "my-org":{
                      "collection": [
                            "assembly-rate-limit ratelimit-my-org 10000 50 second on on on off off off \"\" \"1\""
                      ]
                   },
                    "my-other-org":{
                      "collection": [
                            "assembly-rate-limit ratelimit-my-other-org 10000 50 second on on on off off off \"\" \"1\""
                      ]
                   }
                },
                "_catalog":{
                   "my-org":{
                      "my-catalog":{
                         "collection":[
                            "assembly-rate-limit ratelimit-my-catalog-instance 1000 75 second on on on off off off \"\" \"1\""
                         ]
                      }
                   }
                }
             }

    • Customers can use the @exclusive attribute at any child scope to signal not to apply any parent scope.
      • Using above example if the customization at the catalog scope used the exclusive attribute, then catalog my-catalog in organization my-org would no longer get the global scoped or organization scoped rate limit.  It would only apply the catalog scoped rate limits
      • Example Map:

        • { 
            "api-collection":{
                "_global":{
                   "collection":[
                      "assembly-rate-limit ratelimit-global 10000 5 second on on on off off off \"\" \"1\""
                   ]
                },
                "_organization": {
                   "my-org":{
                      "collection": [
                            "assembly-rate-limit ratelimit-my-org 10000 50 second on on on off off off \"\" \"1\""
                      ]
                   }
                },
                "_catalog":{
                   "my-org":{
                      "my-catalog":{
                         "@exclusive":true,
                         "collection":[
                            "assembly-rate-limit ratelimit-my-catalog-instance 1000 75 second on on on off off off \"\" \"1\""
                         ]
                      }
                   }
                }
             }

• • • Higher level instance scopes such as global instance, organization instance, catalog instance, and product instance provide a way to define customizations to all objects in that scope that match a particular criteria.  For the most part, this criteria would be the name of the object as defined on APIM.
      • Example:  A customer could define a customization at global instance for all TLS Client Profiles with the name and version my-special-tls 1.0.0.  This would then automatically apply the override to all instances of that profile regardless what organization or catalog it was used in.  Below we have a global and global instance. First it would apply the global customization of restricting the use of cipher AES_256_GCM-SHA384 for all TLS Client profiles.  Then it would apply the global instance customization for SNI settings to all instances of my-special-tls 1.0.0.
        Map: 

        {
           "tls-client":{
              "_global":{
                 "_instance":{
                    "my-special-tlsV1.0.0":{
                       "profile":[
                          "use-custom-sni-hostname yes",
                          "custom-sni-hostname my.custom.hostname.com"
                       ]
                    }
                 },
                 "profile":[
                    "no ciphers AES_256_GCM_SHA384"
                 ]
              }
           }
        }

  • Below I will provide more examples which not only show the JSON map but also how they are applied to the cfg's created by the API Connect Gateway Service.  This will give a better view of how and in what order the scoped customizations are applied.
    
    
• The manifest entry for the gwd_extension has the following properties:
  • filename:  name of the file that contains the json mapping 
  • deploy:  Immediate or deferred
    • Deferred means you have to restart the apic-gw-service to apply the customizations.
      • This can be done in the cli using the following commands
        • top;co;apic;admin disabled; exit;apic;admin enabled; exit
  • type:  gwd_extension
  • Example:
    

    {
       "extension":{
          "files":[
             {
                "filename":"overrides.json",
                "type":"gwd_extension",
                "deploy": "immediate"
             }
          ]
       }
    }

• Supported objects for customizations/overrides:

Troubleshooting:

• Once we have added the extension to a registered service in the Cloud Manager, we can confirm the extension was accepted by checking local:/extension/manifest.json.  This will also show all objects that have customizations defined.  If the manifest doesn't show your expected entry then that would suggest it was rejected by the GW.  Check the API Connect Gateway Service logs for details.
  
• Check the cfgs in temporary:/config to see if the overrides were injected as expected.
  • If the customizations are in the cfg file but are not being applied to the object as expected, check the cfg log file for errors.
• Check API Connect Gateway Service logs at debug level for more processing details

More GWD Extension Examples:

1. Parse Settings
2. Front Side Handler and SNI Profile
3. API Gateway
4. TLS Client Profile
5. Catalogs/Collections

• Parse Settings:

  • This is a single object used by the entire service. 
    • In cases where there is only one object for the service then the only scope that can be configured is _global.
  • Increase max size
    

    {
       "parse-settings":{
          "_global":{
             "override":[
                "document-size 5368709121"
             ]
          }
       }
    }

• • Parse setting before override is applied:
    
  • Parse setting after override is applied:
    
    
  • cfg file in temporary:/config/01.parse-settings.cfg:
    
• Note: all customizations will be applied right before the exit for that object and is surrounded by start/end overrides comments.
  
  

• Front side handler and related objects used by the APIGW

• • The Front side handler for the APIGW is also a single object used by the service so only global can be configured.  It does however reference an SNI server profile which in turn has and SNI map.  The SNI map has 1 to many TLS server profiles to be used based on a hostname.  For those TLS profiles you can customize the instance of profile that maps to a particular host name. 
  • For this example we will:
    • Set max http streams for the FSH to 50
    • Change the default TLS server profile in the SNI server object to one we have preconfigured
    • Restrict a cipher on all TLS server profiles used by APIGW except for the one that is used for host “example.com" by using the exclusive attribute
    • Turn compression on for the TLS server profile used for host “example.com"
  • JSON Map:
    

    {
       "front-side-handler":{
          "_global":{
             "source-https":[
                "http2-max-streams 50"
             ],
             "ssl-sni-server":[
                "sni-server-default my_sni_default"
             ],
             "ssl-server":{
                "_instance":{
                   "example.com":{
                      "@exclusive":true,
                      "profile":[
                         "compression on"
                      ]
                   }
                },
                "profile":[
                   "no ciphers DHE_RSA_WITH_AES_128_CBC_SHA"
                ]
             }
          }
       }
    }

    
    
  • FSH Before Customizations
    
    
    
  • FSH after customizations:
    
  • temporary:/config/10.gateway_front-protocol.cfg
    
    
  • SNI Server Before:
    
    
  • SNI Server After
    
    
  • temporary:/config/10.gateway_front-protocol.cfg
    
    
  • SNI TLS Server Profile After:
    
    
  • SNI TLS Server profile mapped to host Example.com Before:
    
    
  • SNI TLS Server profile mapped to host Example.com After:
    
    
  • temporary:/config/10.gateway_front-protocol.cfg
    
    
    
    

• API Gateway

  • Another object type where there is only one per registered service so we can only use the global scope
  • For the this example we are adding assembly rate limits to the apigw object.
    

    {
       "apigw":{
          "”_global”":{
             "override":[
                "assembly-rate-limit ratelimit-reject-ALL 10000 5 second on on on off off off \"\" \"1\"",
                "assembly-rate-limit ratelimit-alert-ALL 7500 5 second off on on off off off \"\" \"1\""
             ]
          }
       }
    }

    
    
  • APIGW before customizations:
    
  •  APIGW after customizations:
    
    
    
  • temporary:/config/30.gateway.cfg
    
    
    

• TLS Client Profiles

  • TLS client profiles can be defined in the cloud manager or in a provider organization.  To use them the customer will then attach the profile to a catalog in the catalog settings tab.
  • In this example we will define several scopes:
    • global
      • Restrict a cipher for all tls client profiles
      • Turn date check off for the valcreds used by all profiles
    • global instance
      • Enable use-custom-sn-hostname and define the hostname to use for all instances of profiles with name and version my-special-tls 1.0.0
    • instance
      • Enable use-custom-sn-hostname and define the hostname to use for the profile with name and version my-tls-profile 1.0.0 in organization my-org and catalog my-catalog
  • JSON Map:
    

    {
       "tls-client":{
          "_global":{
             "_instance":{
                "my-special-tlsV1.0.0":{
                   "profile":[
                      "use-custom-sni-hostname yes",
                      "custom-sni-hostname my.custom.hostname.com"
                   ]
                }
             },
             "profile":[
                "no ciphers DHE_RSA_WITH_AES_128_CBC_SHA"
             ],
             "valcred":[
                "check-dates off"
             ]
          },
          "_instance":{
             "my-org":{
                "my-catalog":{
                   "my-tls-profileV1.0.0":{
                      "profile":[
                         "use-custom-sni-hostname yes",
                         "custom-sni-hostname my.custom.instance.hostname.com"
                      ]
                   }
                }
             }
          }
       }
    }

    
    
  • My-special-tls 1.0.0 in my-org/my-catalog before:
    
  • My-special-tls 1.0.0 in my-org/my-catalog after:
    
  • temporary:/config/20.my-org_my-catalog_collection.cfg
    
    Note: the overrides first apply the global cipher restriction then apply global instance sni host name
    
    
  • My-tls 1.0.0 in the my-org/my-catalog cfg before:
    
  • My-tls 1.0.0 in the my-org/my-catalog cfg after:
    
    
  • temporary:/config/20.my-org_my-catalog_collection.cfg
    
    
  • Note: the overrides first apply the global cipher restriction then applies the instance sni host name. 
    
    
    
  • Valcreds before:
    
    
    
  • Valcred after:
    
    
    
  • temporary:/config/20.my-org_my-catalog_collection.cfg
    
    
    

• Catalog/Collection

  • For the this example we will use global scope to add assembly rate limits to all collection objects except for the instance my-catalog in my-org.  For that catalog we will leverage the exclusive attribute to define a different set of assembly rate limits.
  • JSON Map:
    

    {
       "api-collection":{
          "_global":{
             "collection":[
                "assembly-rate-limit ratelimit-reject-catalog-ALL 10000 5 second on on on off off off \"\" \"1\"",
                "assembly-rate-limit ratelimit-catalog-alert-ALL 7500 5 second off on on off off off \"\" \"1\""
             ]
          },
          "_catalog":{
             "my-org":{
                "my-catalog":{
                   "@exclusive":true,
                   "collection":[
                      "assembly-rate-limit ratelimit-reject-catalog-ALL 1000 5 second on on on off off off \"\" \"1\"",
                      "assembly-rate-limit ratelimit-catalog-alert-ALL 750 5 second off on on off off off \"\" \"1\""
                   ]
                }
             }
          }
       }
    }

    
    
  • My-org/sandbox before:
    
    
  • My-org/sandbox after:
    
    
  • temporary:/config/20.my-org_sandbox_collection.cfg
    
    
  • My-org/my-catalog before:
    
    
  • My-org/my-catalog after:
    
    
  • temporary:/config/20.my-org_my-catalog_collection.cfg
    
    
  
  Knowledge Center Link for gwd_extension
  
  Example gwd_extension, this contains samples for most of the supported objects and child objects.