Cycle Logo

Resource IDs and Identifiers

When working with Cycle, it's important to understand how to uniquely identify and reference resources (hubs, environments, containers, etc.) throughout the platform. This is especially important when working with the API .

There are several types of identifiers, each with a specific purpose.

Resource ID

All resources in Cycle has an associated ID. Resource IDs are static and will never change. A resource ID points to exactly one resource.

A resource ID looks like this:

5a14ddd8b6393d0001976f44

Uses

Resource IDs are used:

  • In the CLI/API/Pipelines to make changes to specific, static resources
  • By our support team when diagnosing issues

Named Identifier

Resources also have a named identifier, which is a more human-friendly way to reference something on Cycle. Most of the time, the named identifier is derived automatically when creating a resource - i.e. from the name field.

The named identifier may be something like app or api, but is customizable. A named identifier is not unique and may point to multiple resources.

Uses

Named identifiers are used:

  • With deployments to refer to a container via LINKED records. For example, a record may point to the container identifier website, which corresponds to a container in a deployment. Whenever a deployment goes out, the record will always point to the website container within that deployment. The actual container (ID) will change, but the record consistently points to the correct website container.
  • In the CLI, instead of memorizing IDs.

Resource Path Identifier

Resource path identifiers are used to narrowly point to a resource by identifier. For example, if there are two environments A, and B, with a container that has the identifier website, but only the container in environment A is desired, a resource path identifier can narrow the scope.

A resource path identifier consists of a resource type, ID OR identifier, and a separator. The separator can be a / or ,.

A resource path identifier looks like this:

cluster:cluster-identifier/environment:environment-identifier/container:container-identifier

environment:5a14ddd8b6393d0001976322/container:abc

cltr:production,stk:5a14ddd8b6393d0001976111

Valid resource types are:

  • cluster
  • environment
  • container
  • image-source
  • stack
  • server
  • pipeline

The resource types can also be referred to using a shorthand:

  • cltr
  • env
  • cntr
  • img-src
  • stk
  • srv
  • pipe

A resource path identifier is not unique and may point to multiple resources. Multiple types/identifiers can be combined to further limit the scope.

Uses

  • Resource path identifiers are particularly useful in pipelines and the CLI for referencing one or more specific resources.