# 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