Template

Reverse Provisioning Template

Every component on witboost is associated to a use case template id that identifies the template it has been created from and keeps a reference to an infrastructure template which is used to identify the technology adapter that can interact with the infrastructure service(s) on which the component is physically deployed.

To run a reverse provisioning operation on a deployment unit component, its related technology adapter may need some information from the user (e.g. a token, a table name, an URL, ...). Hence, the Platform Team needs to have a tool that allows them to define the required inputs from users when initiating a reverse provisioning operation on a component.

The ReverseProvisioningTemplate entity kind allows to define a set of reverse provisioning input params and link them to one or more use case template ids. When a user heads to a component page and a ReverseProvisioningTemplate entity related to the component's use case template id is found, then they will have the possibility to proceed to the reverse provisioning import wizard where the first step will render an input form based on the params definition stored into the ReverseProvisioningTemplate entity.

Entity definition

To define a new ReverseProvisioningTemplate entity, the Platform Team has to create a reverse-provisioning-template.yaml file with the following properties in a git repository:

field	type	description
apiVersion	string	fixed to agilelab.it/v1alpha1
kind	string	fixed to ReverseProvisioningTemplate
metadata	EntityMetadata	witboost entity standard metadata (e.g. metadata.name)
spec.domain	string (optional)	Entity domain
spec.owner	string (optional)	Entity owner
spec.useCaseTemplateId	list[string] (optional)	This ReverseProvisioningTemplate will be associated to each deployment unit component with useCaseTemplateId among the provided ones
spec.useCaseTemplateRef	list[string] (optional)	Complete reference (type:namespace/name) to one or more use case template entities (e.g. template:default/dataproduct-template). spec.useCaseTemplateId will be automatically filled with the useCaseTemplateIds of the referenced templates.
spec.parameters	object	Definition of the reverse provisioning input params

note

In the table above a dot (.) in the field name indicates a relation between an object and its property. E.g. spec.owner and spec.domain translates to

note

If no spec.domain is specified, the ReverseProvisioningTemplate entity will be available for all users if RBAC is enabled.

spec:
  domain: domain-value
  owner: owner-value

note

You can fill both spec.useCaseTemplateId and spec.useCaseTemplateRef arrays. The resulting ReverseProvisioningTemplate entity will process and merge their elements in a single spec.useCaseTemplateId array.

Property spec.parameters stick to the same templating language used inside the definition of a use case template (property spec.parameters inside template.yaml). The only difference is that spec.parameters of template.yaml may accept a list of parameter objects, while spec.parameters of reverse-provisioning-template.yaml expects a single object that will be rendered in UI form.

tip

All values in the configurations.yaml file, if the file is present in the repository, are automatically included in the params field, under the environmentSpecificConfig key, along with all the spec.parameters field in the template. You can change the default key by specifying in your configuration file:

mesh:
  builder:
    scaffolder:
      reverseProvisioning:
        environmentSpecificConfigKey: yourCustomKeyName

Moreover, inside the params field, it is present the descriptor key, containing the entire descriptor of the component. You can change the key name by specifying in your configuration file:

mesh:
  builder:
    scaffolder:
      reverseProvisioning:
        descriptorKey: yourCustomKeyName

To learn more, read the tip here.

Sample reverse-provisioning-template.yaml

apiVersion: witboost.com/v1
kind: ReverseProvisioningTemplate
metadata:
  name: test-reverse-prov-template
spec:
  owner: group:agile_lab
  domain: domain:organization
  useCaseTemplateId:
    - urn:dmb:utm:aws-cdp-outputport-impala-template:0.0.0
  parameters:
    required:
      - table
    properties:
      database:
        title: Database name
        type: string
        description: Impala Database name
      table:
        title: Table name
        type: string
        description: Impala table name
      format:
        title: Format
        type: string
        description: File format
        enum:
          - PARQUET
          - CSV
        enumNames:
          - 'Parquet'
          - 'CSV'
      ignoreTechnicalColumns:
        title: Ignore technical columns
        type: boolean

This specification will create a ReverseProvisioningTemplate entity, associated with each component with a use case template id equal to urn:dmb:utm:aws-cdp-outputport-impala-template:0.0.0. When a user opens the reverse provisioning import wizard on one of these components, they will be presented with the form in the following image:

note

Even if not explicitly defined in the ReverseProvisioningTemplate, the import wizard will always render a mandatory environment field. It is used to target the environment for the provisioning data collection.

Templating language

To better understand the templating language for reverse provisioning parameters and the available input field types check this page and this one.

tip

To test a form definition and preview how it will be rendered, you can exploit the Template Editor located at https://<witboost-url>/wb-scaffolder/edit. It is not specifically intended for reverse provisioning templates but it can serve as a good visual preview tool.

Entity registration

Once the reverse-provisioning-template.yaml file is ready, it's time to register the related entity inside witboost.

Automated way

When a reverse-provisioning-template.yaml is placed in the same folder as a witboost use case template's template.yaml file, it will be automatically fetched by witboost and the related ReverseProvisioningTemplate entity will be registered (or refreshed).

Manual way

It's also possible to manually register ReverseProvisioningTemplate entities from the Catalog Import page https://<witboost-url>/catalog-import (Builder > Templates > Register Existing Component button) by referencing the reverse-provisioning-template.yaml git location.

Template reloading

In order to reflect the modifications made on the reverse-provisioning-template.yaml to the witboost ReverseProvisioningTemplate entity you have two options:

1. wait for witboost to automatically fetch and sync the changes (it is usually done every 90 seconds)
2. Builder > Software Catalog > Filter for ReverseProvisioningTemplates > Open the target entity page > Click on the refresh icon

Documentation

ReverseProvisioningTemplate entities can be documented exactly like other witboost entities. Check this section for additional details.

The documentation can then be read from the ReverseProvisioningTemplate catalog page (Docs tab) and will also be accessible from the Reverse Provisioning Import Wizard on components associated to the documented template.

tip

It is strongly recommended to provide clear documentation of the output (the metadata that will be imported) the user can expect after running the reverse provisioning operation.

Reverse Provisioning Template Checklist

The following checklist can be used to verify if a ReverseProvisioningTemplate entity has been loaded successfully and is semantically correct.

• Go to Builder > Software Catalog > Filter for ReverseProvisioningTemplates

  • Check: the target entity is found
  • Open the entity page
    • Check: no errors are displayed
    • Check: in case you documented the entity, the Docs tab correctly renders it

• Go to Builder > Templates

  • Check: every use case template listed in the spec.useCaseTemplateRef field in reverse-provisioning-template.yaml - or every template that generates components with one of the use case template ids in spec.useCaseTemplateId - features a clickable magic wand icon that redirects to ReverseProvisioningTemplate entity page.

  

  info

  The magic wand icon on a use case template card indicates that every component created starting from that use case template is suitable for the reverse provisioning operation; the reverse provisioning input parameters are defined by the ReverseProvisioningTemplate entity referenced by the icon hyperlink.

• Open the reverse provisioning input wizard of one of the target components

  • Check: the input form in the first step of the wizard is correctly rendered and it's the desired one
  • Check: in case you documented the ReverseProvisioningTemplate entity, an info icon on the upper right corner of the wizard is displayed and it links to the documentation

Entity removal

A ReverseProvisioningTemplate entity can be unregistered from the Software Catalog (Builder > Software Catalog > Filter for ReverseProvisioningTemplates > Find the target entity) just like any other catalog entity.

caution

If you unregister an entity whose reverse-provisioning-template.yaml is placed in the same folder of a witboost use case template's template.yaml file, it will be automatically reloaded by witboost (see the Automated entity registration section above). In this case, please remember to first remove reverse-provisioning-template.yaml from the repository before deleting the related entity from the Software Catalog.