threescale-cicd/CUSTOM.md

How to customize the behavior of this role

Speed-up the deployments

Go save precious seconds during deployments, you can override the threescale_cicd_throttling variable.

WARNING: the throttling is there to let the 3scale Admin Portal digest your changes. Use at your own risk!

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_throttling: 0
  roles:
  - nmasse-itix.threescale-cicd

Customize the 3scale Service display name

To have the 3scale Service display name generated from a different pattern (ENV[name-vX.Y] in the following example), override the threescale_cicd_api_name variable.

- hosts: threescale
  gather_facts: no
  vars:
    myenv: TEST
    threescale_cicd_api_name: '{{ myenv }}[{{ threescale_cicd_api_default_name }}-v{{ threescale_cicd_api_version }}]'
  roles:
  - nmasse-itix.threescale-cicd

Provision a custom policy chain

To provision a custom policy chain, you would need to store your custom policy in a file and reference it from the threescale_cicd_policies_to_update variable.

custom-policy-chain.json:

[
  { "name": "cors", "version": "builtin", "configuration": {}, "enabled": true },
  { "name": "headers", "version": "builtin", "configuration": { "request": [ { "op": "set", "header": "X-TEST", "value_type": "plain", "value": "foo" } ] }, "enabled": true },
  { "name": "apicast", "version": "builtin", "configuration": {}, "enabled": true }
]

deploy-api.yaml:

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_policies_to_update: '{{ lookup(''file'', playbook_dir ~ ''/custom-policy-chain.json'')|from_json }}'
  roles:
  - nmasse-itix.threescale-cicd

Implement the url_rewriting policy

If you want to deploy an API that is not yet implemented and would like to route requests to a mock such as Microcks, you will need to implement the url_rewriting policy.

The url_rewriting policy will help you add a prefix to the URL before calling the Mock server: GET /beers becomes GET /rest/Echo+API/1.0/beers.

custom-policy-chain.json.j2:

[
  { "name": "apicast", "version": "builtin", "configuration": {}, "enabled": true },
  { "name": "url_rewriting", "version": "builtin", "configuration": { "query_args_commands": [], "commands": [ { "op": "sub", "regex": "^/", "replace": "/rest/{{ api_name|urlencode }}/{{ threescale_cicd_api_version }}/" } ] }, "enabled": true }
]

deploy-api.yaml:

- hosts: threescale
  gather_facts: no
  vars:
    api_name: Echo API
    threescale_cicd_policies_to_update: '{{ lookup(''template'', playbook_dir ~ ''/custom-policy-chain.json.j2'') }}'
  roles:
  - nmasse-itix.threescale-cicd

Choose the Account in which the smoke test application is created

By default, the playbook will create a client application in the default first account of your tenant (the Account that contains "john"). But you can choose the Account to use by overriding the threescale_cicd_default_account_id variable.

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_default_account_id: '2445582535751'
  roles:
  - nmasse-itix.threescale-cicd

You can find the Account id by navigating to Audience > Accounts > Listing and clicking on the Account of your choice. The ID is the last part of the URL (/buyers/accounts/{id}).

Override the default versioning scheme

By default, the playbook will version your APIs based on the Semantic Versioning scheme. This means minor versions (1.0, 1.1, 1.2, etc) will be deployed continously to the same 3scale service. Major versions are deployed side-by-side (one service for each major version).

If you want to deploy all versions to the same service, no matter what:

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_api_version_major: '0' # or whatever you want as long as it remains static
  roles:
  - nmasse-itix.threescale-cicd

If you want to release minor versions as major versions:

- hosts: threescale
  gather_facts: no
  vars:
    threescale_cicd_api_version_major: '{{ threescale_cicd_api_version_components|first }}-{{ threescale_cicd_api_version_components[1] if threescale_cicd_api_version_components|length > 1 else 0 }}'
  roles:
  - nmasse-itix.threescale-cicd