API documentation

# Description

An environment is a basic organization structure that groups hosts, products, repositories, etc. Every host belongs to one environment and it's isolated inside so that it can see only content that is in its environment.

## Chains

Environments are ordered into chains and their content (products, repositories, tempaltes, packages) can be moved to an environment only from its prior environment. You can have for example chain like:

Library -> Development -> Testing -> Production

Each change in an environment is done through a changeset in an action called promotion.

## Library

Library is a special environment that has no ascendant: All the content starts in this environment. More chains can start from the library environment but no further branching of a chain is enabled.

>>>

GET /katello/api/environments
List environments in an organization

GET /katello/api/organizations/:organization_id/environments
List environments in an organization

Examples

GET /katello/api/environments
200
{
  "total": 14,
  "subtotal": 14,
  "selectable": 14,
  "page": 1,
  "per_page": 20,
  "error": null,
  "search": null,
  "sort": {
    "by": "id",
    "order": "asc"
  },
  "results": [
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 9167524,
      "name": "QA Path1",
      "label": "qa_path1_label",
      "description": "QA environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Dev Path1",
        "id": 413623389
      },
      "successor": {
        "name": "Staging Path1",
        "id": 507881024
      },
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 28194273,
      "name": "Dev Path2",
      "label": "dev_path2_label",
      "description": "Dev environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Library",
        "id": 562075838
      },
      "successor": {
        "name": "QA Path2",
        "id": 427995936
      },
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 122484616,
      "name": "Staging Path2",
      "label": "staging_path2_label",
      "description": "Staging environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "QA Path2",
        "id": 427995936
      },
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 261162085,
      "name": "Beta",
      "label": "beta_label",
      "description": "Beta environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Test_env",
        "id": 411008527
      },
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 292811013,
      "name": "Dev",
      "label": "dev_label",
      "description": "Dev environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Library",
        "id": 562075838
      },
      "successor": {
        "name": "Test_env",
        "id": 411008527
      },
      "counts": {
        "content_hosts": 1,
        "content_views": 2
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": false,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": [
        {
          "name": "Published Library and dev view",
          "id": 909058347
        },
        {
          "name": "Published Library - dev - staging view",
          "id": 419082953
        }
      ]
    },
    {
      "library": true,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 396772849,
      "name": "Library",
      "label": "candlepin_library",
      "description": "This is the Library",
      "organization_id": 61304186,
      "organization": {
        "name": "Organization 2",
        "label": "Organization_2",
        "id": 61304186
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": null,
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 0,
        "packages": 0,
        "module_streams": 0,
        "errata": {
          "security": 0,
          "bugfix": 0,
          "enhancement": 0,
          "total": 0
        },
        "yum_repositories": 0,
        "docker_repositories": 0,
        "ostree_repositories": 0,
        "products": 0,
        "debs": 0,
        "deb_repositories": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": false,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 411008527,
      "name": "Test_env",
      "label": "test_label",
      "description": "Test environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Dev",
        "id": 292811013
      },
      "successor": {
        "name": "Beta",
        "id": 261162085
      },
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 413623389,
      "name": "Dev Path1",
      "label": "dev_path1_label",
      "description": "Dev environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Library",
        "id": 562075838
      },
      "successor": {
        "name": "QA Path1",
        "id": 9167524
      },
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 427995936,
      "name": "QA Path2",
      "label": "qa_path2_label",
      "description": "QA environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Dev Path2",
        "id": 28194273
      },
      "successor": {
        "name": "Staging Path2",
        "id": 122484616
      },
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 507881024,
      "name": "Staging Path1",
      "label": "staging_path1_label",
      "description": "Staging environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "QA Path1",
        "id": 9167524
      },
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": true,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 562075838,
      "name": "Library",
      "label": "library_label",
      "description": "This is the Library",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": null,
      "successor": null,
      "counts": {
        "content_hosts": 2,
        "content_views": 4,
        "packages": 5,
        "module_streams": 2,
        "errata": {
          "security": 1,
          "bugfix": 1,
          "enhancement": 1,
          "total": 3
        },
        "yum_repositories": 11,
        "docker_repositories": 4,
        "ostree_repositories": 1,
        "products": 8,
        "debs": 4,
        "deb_repositories": 5
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": false,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": [
        {
          "name": "Published LIbrary view",
          "id": 405955044
        },
        {
          "name": "Published Library and dev view",
          "id": 909058347
        },
        {
          "name": "Published Library - dev - staging view",
          "id": 419082953
        },
        {
          "name": "Composite view",
          "id": 64601712
        }
      ]
    },
    {
      "library": true,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 779215191,
      "name": "Library",
      "label": "organization1_library",
      "description": "This is the Library",
      "organization_id": 447626438,
      "organization": {
        "name": "Organization 1",
        "label": "Organization_1",
        "id": 447626438
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": null,
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 0,
        "packages": 0,
        "module_streams": 0,
        "errata": {
          "security": 0,
          "bugfix": 0,
          "enhancement": 0,
          "total": 0
        },
        "yum_repositories": 0,
        "docker_repositories": 0,
        "ostree_repositories": 0,
        "products": 0,
        "debs": 0,
        "deb_repositories": 0
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": false,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": []
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 797271385,
      "name": "Candlepin Dev",
      "label": "candlepin_dev_label",
      "description": "Dev environment.",
      "organization_id": 61304186,
      "organization": {
        "name": "Organization 2",
        "label": "Organization_2",
        "id": 61304186
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Library",
        "id": 396772849
      },
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 1
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": [
        {
          "name": "Candlepin Library and Dev Content View",
          "id": 566851579
        }
      ]
    },
    {
      "library": false,
      "registry_name_pattern": null,
      "registry_unauthenticated_pull": false,
      "id": 1028819239,
      "name": "Staging",
      "label": "staging_label",
      "description": "Staging environment.",
      "organization_id": 114267492,
      "organization": {
        "name": "Empty Organization",
        "label": "Empty_Organization",
        "id": 114267492
      },
      "created_at": "2023-08-23 19:55:45 UTC",
      "updated_at": "2023-08-23 19:55:45 UTC",
      "prior": {
        "name": "Library",
        "id": 562075838
      },
      "successor": null,
      "counts": {
        "content_hosts": 0,
        "content_views": 1
      },
      "permissions": {
        "create_lifecycle_environments": true,
        "view_lifecycle_environments": true,
        "edit_lifecycle_environments": true,
        "destroy_lifecycle_environments": true,
        "promote_or_remove_content_views_to_environments": true
      },
      "content_views": [
        {
          "name": "Published Library - dev - staging view",
          "id": 419082953
        }
      ]
    }
  ]
}

Params

Param name	Description
organization_id optional	organization identifier Validations: Must be a number.
library optional	set true if you want to see only library environments Validations: Must be one of: `true`, `false`, `1`, `0`.
name optional	filter only environments containing this name Validations: String
label optional	filter only environments containing this label Validations: String
search optional	Search string Validations: String
page optional	Page number, starting at 1 Validations: Must be a number.
per_page optional	Number of results per page to return Validations: Must be a number.
order optional	Sort field and order, eg. 'id DESC' Validations: String
full_result optional	Whether or not to show all results Validations: Must be one of: `true`, `false`, `1`, `0`.
sort_by optional	Field to sort the results on Validations: String
sort_order optional	How to order the sorted results (e.g. ASC for ascending) Validations: String

Search fields

Field name	Type	Possible values
id	integer
label	string
name	string
organization_id	integer

>>>

GET /katello/api/environments/:id
Show an environment

GET /katello/api/organizations/:organization_id/environments/:environment_id
Show an environment

Params

Param name

Description

id
required

ID of the environment

Validations:

Must be a number.

organization_id
optional

ID of the organization

Validations:

Must be a number.

>>>

POST /katello/api/environments
Create an environment

POST /katello/api/organizations/:organization_id/environments
Create an environment in an organization

Examples

POST /katello/api/organizations/114267492/environments
{
  "environment": {
    "name": "dev env",
    "label": "dev_env",
    "description": "This environment is for development.",
    "prior": 562075838
  }
}
204

Params

Param name	Description
organization_id required	name of organization Validations: Must be a number.
name required	name of the environment Validations: String
label optional	label of the environment Validations: String
description optional	description of the environment Validations: String
registry_name_pattern optional	pattern for container image names Validations: String
registry_unauthenticated_pull optional	allow unauthenticed pull of container images Validations: Must be one of: `true`, `false`, `1`, `0`.
prior_id required	ID of an environment that is prior to the new environment in the chain. It has to be either the ID of Library or the ID of an environment at the end of a chain. Validations: Integer

>>>

PUT /katello/api/environments/:id
Update an environment

PUT /katello/api/organizations/:organization_id/environments/:id
Update an environment in an organization

Examples

PUT /katello/api/organizations/114267492/environments/1028819239
{
  "environment": {
    "new_name": "New Name",
    "label": "New Label",
    "registry_name_pattern": "<%= repository.label %> <%= organization.label %>"
  }
}
200
{
  "library": false,
  "registry_name_pattern": "<%= repository.label %> <%= organization.label %>",
  "registry_unauthenticated_pull": false,
  "id": 1028819239,
  "name": "New Name",
  "label": "staging_label",
  "description": "Staging environment.",
  "organization_id": 114267492,
  "organization": {
    "name": "Empty Organization",
    "label": "Empty_Organization",
    "id": 114267492
  },
  "created_at": "2023-08-23 19:55:45 UTC",
  "updated_at": "2023-08-23 20:04:02 UTC",
  "prior": {
    "name": "Library",
    "id": 562075838
  },
  "successor": null,
  "counts": {
    "content_hosts": 0,
    "content_views": 1
  },
  "permissions": {
    "create_lifecycle_environments": true,
    "view_lifecycle_environments": true,
    "edit_lifecycle_environments": true,
    "destroy_lifecycle_environments": true,
    "promote_or_remove_content_views_to_environments": true
  },
  "content_views": [
    {
      "name": "Published Library - dev - staging view",
      "id": 419082953
    }
  ]
}

Params

Param name	Description
id required	ID of the environment Validations: Must be a number.
organization_id optional	name of the organization Validations: Must be a number.
new_name optional	new name to be given to the environment Validations: String
description optional	description of the environment Validations: String
registry_name_pattern optional	pattern for container image names Validations: String
registry_unauthenticated_pull optional	allow unauthenticed pull of container images Validations: Must be one of: `true`, `false`, `1`, `0`.
async optional	Do not wait for the update action to finish. Default: true Validations: Must be one of: `true`, `false`, `1`, `0`.

>>>

DELETE /katello/api/environments/:id
Destroy an environment

DELETE /katello/api/organizations/:organization_id/environments/:id
Destroy an environment in an organization

Examples

DELETE /katello/api/organizations/114267492/environments/1028819258
{
  "environment": {}
}
200
{
  "library": false,
  "registry_name_pattern": null,
  "registry_unauthenticated_pull": false,
  "id": 1028819258,
  "name": "DestroyAble",
  "label": "DestroyAble",
  "description": null,
  "organization_id": 114267492,
  "organization": {
    "name": "Empty Organization",
    "label": "Empty_Organization",
    "id": 114267492
  },
  "created_at": "2023-08-23 20:04:02 UTC",
  "updated_at": "2023-08-23 20:04:02 UTC",
  "prior": {
    "name": "Staging",
    "id": 1028819239
  },
  "successor": null,
  "counts": {
    "content_hosts": 0,
    "content_views": 0
  },
  "permissions": {
    "create_lifecycle_environments": true,
    "view_lifecycle_environments": true,
    "edit_lifecycle_environments": true,
    "destroy_lifecycle_environments": true,
    "promote_or_remove_content_views_to_environments": true
  },
  "content_views": []
}

Params

Param name

Description

id
required

ID of the environment

Validations:

Must be a number.

organization_id
optional

organization identifier

Validations:

Must be a number.

>>>

GET /katello/api/organizations/:organization_id/environments/paths
List environment paths

Examples

GET /katello/api/organizations/114267492/environments/paths
204

Params

Param name

Description

organization_id
optional

organization identifier

Validations:

Must be a number.

content_source_id
optional

Show whether each lifecycle environment is associated with the given Smart Proxy id.

Validations:

Must be a number.

permission_type
optional

The associated permission type. One of (readable | promotable) Default: readable

Validations:

String

Lifecycle_environments

GET /katello/api/environments List environments in an organization

GET /katello/api/organizations/:organization_id/environments List environments in an organization

Examples

Params

Search fields

GET /katello/api/environments/:id Show an environment

GET /katello/api/organizations/:organization_id/environments/:environment_id Show an environment

Params

POST /katello/api/environments Create an environment

POST /katello/api/organizations/:organization_id/environments Create an environment in an organization

Examples

Params

PUT /katello/api/environments/:id Update an environment

PUT /katello/api/organizations/:organization_id/environments/:id Update an environment in an organization

Examples

Params

DELETE /katello/api/environments/:id Destroy an environment

DELETE /katello/api/organizations/:organization_id/environments/:id Destroy an environment in an organization

Examples

Params

GET /katello/api/organizations/:organization_id/environments/paths List environment paths

Examples

Params

GET /katello/api/environments
List environments in an organization

GET /katello/api/organizations/:organization_id/environments
List environments in an organization

GET /katello/api/environments/:id
Show an environment

GET /katello/api/organizations/:organization_id/environments/:environment_id
Show an environment

POST /katello/api/environments
Create an environment

POST /katello/api/organizations/:organization_id/environments
Create an environment in an organization

PUT /katello/api/environments/:id
Update an environment

PUT /katello/api/organizations/:organization_id/environments/:id
Update an environment in an organization

DELETE /katello/api/environments/:id
Destroy an environment

DELETE /katello/api/organizations/:organization_id/environments/:id
Destroy an environment in an organization

GET /katello/api/organizations/:organization_id/environments/paths
List environment paths