Collection Versions
Contents
Collection Versions
Collections are the building blocks for installing and configuring the software using Ansible. A collection can be regarded as a package of modular codified system administration, which encompasses a set of system administration playbooks that allow fine-grained configuration. When preparing a template for a server, specific versions of different collections can be used, and these can be specified to be Ansible Galaxy collections maintained by the community or custom collections prepared by users themselves. The API requests we describe below allow managing the set of custom collection versions available to the user in the platform.
List Collection Versions
GET /v3/blueprint/ansible_collection_versions
It lists all available collection versions.
Inputs
None
Returns
An array of collection versions with the following format:
| Field | Type | Description |
|---|---|---|
| id | String | Identifier of the collection version. |
| name | String | Name of the collection. |
| version | String | The version of the collection, three natural numbers separated by dots. |
| description | String | Description of the collection version's purpose. |
| publicly_available | Boolean | Whether this collection version is available to all users, false for any collection version uploaded by a user |
| state | String | One of "created", "processing", "duplicated", "ready" or "processing_error", the status of the collection version and its availability to be used in a template. |
| error_message | String | Optional, this field may describe the reason why a collection version transitioned to the "processing_error" state. |
| revision_id | String | A checksum identifying the contents of the collection version. |
| playbooks | Array of strings | A list of playbooks that the collection version encompasses. |
| global_legacy | Boolean | Optional, if present and set to true, it indicates the collection version used to be a publicly available one but was deprecated as such in the platform and may no longer be compatible with the version of ansible currently in use. |
| label_ids | Array of strings | List of ids corresponding to the labels the collection version has assigned. |
| resource_type | String | An identifier for the type of resource, specifically "collection_version". |
Show Collection Version
GET /v3/blueprint/collection_versions/:id
It shows information about a specific collection version.
Inputs
None
Returns
| Field | Type | Description |
|---|---|---|
| id | String | Identifier of the collection version. |
| name | String | Name of the collection. |
| version | String | The version of the collection, three natural numbers separated by dots. |
| description | String | Description of the collection version's purpose |
| license | String | The license of the software included in the collection version. |
| long_description | String | A longer description of the collection version's purpose, normally including documentation about its use. |
| attribute_metadata | Object | Optional, if the collection version defines it in its metadata, the attribute metadata: an object with attribute paths as keys and objects specifying the following attribute properties: "calculated", "choice","default", "description", "display_name", "required" and "type". |
| default_attributes | Object | If the collection version defines attribute metadata, an object with the default values this will take when used in a template. |
| publicly_available | Boolean | Whether this collection version is available to all users, false for any collection version uploaded by a user. |
| state | String | One of "created", "processing", "duplicated", "ready" or "processing_error", the status of the collection version and its availability to be used in a template. |
| error_message | String | Optional, this field may describe the reason why a collection version transitioned to the "processing_error" state. |
| revision_id | String | A checksum identifying the contents of the collection version. |
| playbooks | Array of strings | A list of playbooks that the collection version encompasses. |
| global_legacy | Boolean | Optional, if present and set to true, it indicates the collection version used to be a publicly available one but was deprecated as such in the platform and may no longer be compatible with the version of ansible currently in use. |
| label_ids | Array of strings | List of ids corresponding to the labels the collection version has assigned. |
| duplicate_collection_version_id | String | Optional, it indicates the Id of the collection version already in the system that this collection version is duplicated of if any. |
| duplicate_collection_version_revision_id | String | Optional, present if there is a duplicate_collection_version_id, indicates the revision id of the collection version already in the system that this collection version is duplicated of. |
| download_url | String | Url where the collection can be downloaded. |
| resource_type | String | An identifier for the type of resource, specifically "collection_version". |
Create Collection Version
POST /v3/blueprint/collection_versions
It creates a new collection version record.
Inputs
| Field | Type | Description | Required |
|---|---|---|---|
| is_mock | String | Indicates whether this collection version is intended to be used for testing or not | Yes |
Returns
| Field | Type | Description |
|---|---|---|
| id | String | Identifier of the collection version. |
| name | String | Name of the collection. |
| version | String | The version of the collection, three natural numbers separated by dots. |
| description | String | Description of the collection version's purpose |
| license | String | The license of the software included in the collection version. |
| long_description | String | A longer description of the collection version's purpose, normally including documentation about its use. |
| attribute_metadata | Object | Optional, if the collection version defines it in its metadata, the attribute metadata: an object with attribute paths as keys and objects specifying the following attribute properties: "calculated", "choice","default", "description", "display_name", "required" and "type". |
| default_attributes | Object | If the collection version defines attribute metadata, an object with the default values this will take when used in a template. |
| publicly_available | Boolean | Whether this collection version is available to all users, false for any collection version uploaded by a user. |
| state | String | One of "created", "processing", "duplicated", "ready" or "processing_error", the status of the collection version and its availability to be used in a template. |
| error_message | String | Optional, this field may describe the reason why a collection version transitioned to the "processing_error" state. |
| revision_id | String | A checksum identifying the contents of the collection version. |
| playbooks | Array of strings | A list of playbooks that the collection version encompasses. |
| global_legacy | Boolean | Optional, if present and set to true, it indicates the collection version used to be a publicly available one but was deprecated as such in the platform and may no longer be compatible with the version of ansible currently in use. |
| label_ids | Array of strings | List of ids corresponding to the labels the collection version has assigned. |
| duplicate_collection_version_id | String | Optional, it indicates the Id of the collection version already in the system that this collection version is duplicated of if any. |
| duplicate_collection_version_revision_id | String | Optional, present if there is a duplicate_collection_version_id, indicates the revision id of the collection version already in the system that this collection version is duplicated of. |
| download_url | String | Url where the collection can be downloaded. |
| resource_type | String | An identifier for the type of resource, specifically "collection_version". |
Process Collection Version
POST /v3/blueprint/collection_versions/:id/process
It tells the system that the user has already uploaded the collection to the provided URL and it is ready to be processed.
Inputs
None
Returns
| Field | Type | Description |
|---|---|---|
| id | String | Identifier of the collection version. |
| name | String | Name of the collection. |
| version | String | The version of the collection, three natural numbers separated by dots. |
| description | String | Description of the collection version's purpose |
| license | String | The license of the software included in the collection version. |
| long_description | String | A longer description of the collection version's purpose, normally including documentation about its use. |
| attribute_metadata | Object | Optional, if the collection version defines it in its metadata, the attribute metadata: an object with attribute paths as keys and objects specifying the following attribute properties: "calculated", "choice","default", "description", "display_name", "required" and "type". |
| default_attributes | Object | If the collection version defines attribute metadata, an object with the default values this will take when used in a template. |
| publicly_available | Boolean | Whether this collection version is available to all users, false for any collection version uploaded by a user. |
| state | String | One of "created", "processing", "duplicated", "ready" or "processing_error", the status of the collection version and its availability to be used in a template. |
| error_message | String | Optional, this field may describe the reason why a collection version transitioned to the "processing_error" state. |
| revision_id | String | A checksum identifying the contents of the collection version. |
| playbooks | Array of strings | A list of playbooks that the collection version encompasses. |
| global_legacy | Boolean | Optional, if present and set to true, it indicates the collection version used to be a publicly available one but was deprecated as such in the platform and may no longer be compatible with the version of ansible currently in use. |
| label_ids | Array of strings | List of ids corresponding to the labels the collection version has assigned. |
| duplicate_collection_version_id | String | Optional, it indicates the Id of the collection version already in the system that this collection version is duplicated of if any. |
| duplicate_collection_version_revision_id | String | Optional, present if there is a duplicate_collection_version_id, indicates the revision id of the collection version already in the system that this collection version is duplicated of. |
| download_url | String | Url where the collection can be downloaded. |
| resource_type | String | An identifier for the type of resource, specifically "collection_version". |
Destroy Collection Version
DELETE /v3/blueprint/collection_versions/:id
It deletes a collection version.
Inputs
None
Returns
None