API OVERVIEW
Welcome to the Jenkins X API. You can use the Jenkins X API to read
and write Kubernetes resource objects via a Jenkins X API endpoint.
Resource Categories
This is a high-level overview of the basic types of resources provide by the Jenkins X API and their primary
functions.
Apps resources describe extensions to Jenkins X.
Pipelines & Environments resources describe the work being done by Jenkins X.
User Management resources describe the user management done by Jenkins X.
Resource Objects
Resource objects typically have 3 components:
- Resource ObjectMeta: This is metadata about the resource, such as its name, type, api version, annotations, and labels. This contains
fields that maybe updated both by the end user and the system (e.g. annotations).
- ResourceSpec: This is defined by the user and describes the desired state of system. Fill this in when creating or updating an object.
- ResourceStatus: This is filled in by the server and reports the current state of the system. In most cases, users don't need to change this.
Resource Operations
Most resources provide the following Operations:
Create
Create operations will create the resource in the storage backend. After a resource is create the system will apply
the desired state.
Update
Updates come in 2 forms: Replace and Patch:
- Replace:
Replacing a resource object will update the resource by replacing the existing spec with the provided one. For
read-then-write operations this is safe because an optimistic lock failure will occur if the resource was modified
between the read and write. Note: The ResourceStatus will be ignored by the system and will not be updated.
To update the status, one must invoke the specific status update operation.
Note: Replacing a resource object may not result immediately in changes being propagated to downstream objects. For instance
replacing a ConfigMap
or Secret
resource will not result in all Pods seeing the changes unless the Pods are
restarted out of band.
Note: Where possible using Patch
is preferable over UPDATE
as if new fields have been added to the resource object that is not known about by the running code these will be lost.
- Patch:
Patch will apply a change to a specific field. How the change is merged is defined per field. Lists may either be
replaced or merged. Merging lists will not preserve ordering.
Patches will never cause optimistic locking failures, and the last write will win. Patches are recommended
when the full state is not read before an update, or when failing on optimistic locking is undesirable. When patching
complex types, arrays and maps, how the patch is applied is defined on a per-field basis and may either replace
the field's current value, or merge the contents into the current value.
Read
Reads come in 3 forms: Get, List and Watch:
- Get: Get will retrieve a specific resource object by name.
- List: List will retrieve all resource objects of a specific type within a namespace, and the results can be restricted to resources matching a selector query.
List All Namespaces: Like List but retrieves resources across all namespaces.
- Watch: Watch will stream results for an object(s) as it is updated. Similar to a callback, watch is used to respond to resource changes.
Delete
Delete will delete a resource. Depending on the specific resource, child objects may or may not be garbage collected by the server. See
notes on specific resource objects for details.
Additional Operations
Resources may define additional operations specific to that resource type.
- Rollback: Rollback a PodTemplate to a previous version. Only available for some resource types.
- Read / Write Scale: Read or Update the number of replicas for the given resource. Only available for some resource types.
- Read / Write Status: Read or Update the Status for a resource object. The Status can only changed through these update operations.