Create Bundles

Contents:
2
A bundle is a RESTMAN deployable XML artifact that contains gateway entities. For each exported entity type, a configuration yml file is created in the config folder like policies.yml, service.yml, encass.yml, jdbc-connections.yml. You can modify the configuration of these entities by editing any of these files like jdbc connection url change for an entity present in the jdbc-connections.yml file. Create a bundle to deploy the modified entities to your target gateway.
Bundle Types
Gateway Policy Plugin supports building bundles for Gateway-only and Portal-managed Gateway deployments. These bundles can be categorized as shown below:
  • SERVICE
    : Contains service (Web API or SOAP) definition along with its service policy dependencies. 
  • ENCAPSULATED ASSERTION
    : Contains encapsulated assertion along with its encass policy dependencies.
  • ENVIRONMENT
    : Contains environment configuration entities.
  • ALL
    : Contains everything.
You can generate all the bundle types only if you use annotations as specified, except for
ALL
bundle type.
Build Bundles
You can create bundles for the entities that are available in the gradle project
src
folder. Execute the following gradle tasks for creating different type of bundles:
  • Deployment Bundle
    : Deployment bundle contains only gateway code entities like Policy, Encapsulated Assertion, and Service. Execute the following gradle task for generating deployment bundle:
    gradle clean build-bundle
  • Environment Bundle
    : Environment bundle contains only Gateway data entities like Passwords, JDBC Connections, JMS Connections, ID Providers, and so on. Execute the following gradle task for generating a bundle containing only environment entities:
    gradle clean build-environment-bundle
    This task takes the environment entities from
    EnvironmentConfig
    that is defined in the build.gradle file:
    GatewaySourceConfig { EnvironmentConfig { name = "<Configuration Name>", includeFolder = file("src/main/gateway/<configfolder>"), map = [ "<ENTITY_TYPE>.<ENTITY_NAME>" = "Entity Value", "<ENTITY_TYPE>.<ENTITY_NAME>" = file("./src/main/gateway/<configfolder>/<entityconfigfile>"), "<ENTITY_TYPE>" = file("./src/main/gateway/<configfolder>/<entityconfigfile>") ] } }
    To configure the environment, see Environment Configuration.
  • Full Bundle
    : Full bundle contains all the entities that are available in the gradle project
    src
    folder. Execute the following gradle task for generating a bundle that contains both policy entities as well as environment entities:
    gradle clean build-full-bundle
    This task takes the environment entities from
    EnvironmentConfig
    that is defined in the build.gradle file.
    To configure the environment, see Environment Configuration.
    To generate bundles with your choice of entity mapping action, configure the system property,
    com.ca.apim.build.defaultEntityMappingAction
    .
    Unique naming of the environment entities is enabled by default. To disable unique naming, configure the system property,
    com.ca.apim.build.disableEnvironmentEntityUniqueNaming
    .
    See System Properties for more information.
For more Gateway Policy Plugin tasks, see Additional Gateway Policy Plugin Tasks.
The Gateway Policy Plugin builds bundles and generates the following artifacts via the
build-bundle
and
build-environment-bundle
tasks:
  • <
    name
    >-<
    version
    >.metadata.yml
    : Includes information about the generated bundle along with its dependencies.
  • <
    name
    >-<
    version
    >.install.bundle
    : Packages policies, encass, services, and other gateway entities.
  • <
    name
    >-<
    version
    >.delete.bundle
    : Undeploys the bundle.
  • <
    name
    >-<
    version
    >
    -full.{install|delete}.bundle
    : (install) Packages both policy and environment-specific entities. (delete) Undeploys the full bundle.
  • <
    name
    >-environment-<
    version
    >.{install|delete}.bundle
    : Includes environment-specific entities.
Create Full Bundle or Separate Bundles
You can either create a single full bundle or create separate bundles for policies and environments when you want to decouple the environment from policy and maintain multiple environments for a set of policies. So, bundles may contain policy-specific entities, environment-specific entities, or both.
A policy bundle can have zero or more environment bundles. Each environment bundle may correspond to the deployment stages.
Examples:
sample-1.0.00.metadata.yml
sample-1.0.00.install.bundle
sample-1.0.00.delete.bundle
sample-environment-1.0.00.metadata.yml
sample-environment-1.0.00.install.bundle
sample-environment-1.0.00.delete.bundle
sample-1.0.00.metadata.yml
sample-1.0.00-full.install.bundle
sample-1.0.00-full.delete.bundle
Add Bundle Dependencies
You can depend on other bundles by adding a bundle dependency. For example:
dependencies { bundle group: 'my-bundle', name: 'my-bundle', version: '1.0.00', ext: 'bundle' }
The above example adds a dependency on a bundle called 'my-bundle'. You can now reference encapsulated assertions and policies from the dependent bundles. Note that the
ext: 'bundle'
is required to specify that the bundle file extension is
.bundle
. Policies within the dependency bundle can be overridden by local policies in the repository. As an example if there is a policy under 'my-bundle/my-bundle-extension' in the repository, it takes precedence over the policy in 'my-bundle'. You can add dependencies on bundles that are produced by other modules within the same repository. For example, PolicyFolder1 and PolicyFolder2 are two gradle modules and the module containing the below build.gradle file, has dependency on 'PolicyFolder1' and 'PolicyFolder2' bundles.
dependencies { bundle project(':PolicyFolder1') bundle project(':PolicyFolder2') }
Deploy to a Specific Folder
You can also create a bundle to deploy the policies/services to a specified target folder using the following configuration. If the target gateway does not contain the specified target folder, a new folder is created.
GatewaySourceConfig { targetFolderPath = "<Folder Path>" }
Bundle Metadata
Gateway Policy Plugin generates metadata such as basic details like name, version, tags, and defined entities, environment dependencies, and other dependencies for each annotated entity along with the deployment bundle. You need not modify this metadata. This metadata helps any deployment tool in understanding the generated bundle and deploying it. From bundle metadata, a deployer can get information such as bundle dependencies, where it needs to deploy the dependent bundle before deploying the bundle, and so on.
Example:
metaVersion: 1.0 name: <bundle-name> # See Naming convention groupName: <group-name> # Gradle project group name portalTemplate: true|false # Marks the bundle as a portal-friendly reusable template moduleName: <module-name> # Gradle project module name version: <version> # Gradle project version timestamp: <unix-epoch-time-in-seconds> type: SERVICE|ENCAPSULATED_ASSERTION|POLICY|ALL # "ALL" represents the Full Bundle. Contains multiple entities in "definedEntities" tags: - routing - audit - <any> description: <bundle-description> # If description is not present in the @bundle annotation, fallback to entity description. shared: true|false # Always false for service typed bundles, else always true l7Template: true|false # whether given bundle is portal friendly reusable template or not redeployable: true|false hasRouting: true|false definedEntities: # For annotated bundles, this will contain only 1 entity - type: ENCAPSULATED_ASSERTION|POLICY|SERVICE name: <defined-entity-name> id: <goid> guid: <guid> uri: <service-uri> # applicable to SERVICE soap: true|false # applicable to SERVICE arguments: # applicable to both ENCAS and POLICY - type: string|int|boolean|... name: <arg-name> requireExplicit: <gui-prompt> label: <arg-label> results: # applicable to both ENCAS and POLICY - type: string|int|boolean|... name: <result-name> referencedEntities: - type: CLUSTER_PROPERTY|SECURE_PASSWORD|JDBC_CONNECTION|... name: <config-entity-name> dependencies: - type: bundle name: <dependent-bundle-name> groupName: <dependent-bundle-group-name> version: <dependent-bundle-version> # optional
If you are exporting a configuration from earlier versions of Gateway such as v9.4 or v10.0, the
hasRouting
attribute defaults to
false
for a policy as it is not included in the exported bundle.
You can use annotations to mark entities in the configuration files and generate bundles per policy/service. This method provides granular control over which policy/service to deploy.