Chapter 2. Preparing Resources

2.1. Projects

2.1.1. Description of Resource

Projects are the unit of isolation and collaboration in OpenShift. A project has one or more members, a quota on the resources that the project may consume, and the security controls on the resources in the project. Within a project, members may have different roles - project administrators can set membership, editors can create and manage the resources, and viewers can see but not access running containers. In typical clusters, cluster administrators, rather than project administrators, can alter project quotas.

Listing or watching projects will return only projects the user has the reader role on.

An OpenShift project is an alternative representation of a Kubernetes namespace. Projects are exposed as editable to end users while namespaces are not. Direct creation of a project is typically restricted to administrators, while end users should use the ProjectRequest resource.

2.1.2. Creating a New Project as Administrator

2.1.2.1. Request Breakdown

Creating a new project as an administrator requires one request:

A POST request to the projects resource.

The POST request to the projects resource uses a Project configuration in the request body.

2.1.2.2. POST Request to Create a New Project

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/projects

Request Body

apiVersion: v1
kind: Project
metadata:
  name: {$PROJECT_NAME}

2.1.3. Creating a New Project as User

2.1.3.1. Request Breakdown

Creating a new project as a user requires one request:

A POST request to the projectrequests resource.

The POST request uses a ProjectRequest configuration in the request body.

2.1.3.2. POST Request to Create a New Project

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/projectrequests

Request Body

apiVersion: v1
kind: ProjectRequest
metadata:
  name: {$PROJECT_NAME}

2.1.4. Listing all Projects in an Environment

2.1.4.1. Request Breakdown

Listing all the projects in an environment requires one request:

A GET request to the projects resource.

The GET request returns a ProjectList configuration.

2.1.4.2. GET Request to List all Projects

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/projects

2.1.5. Listing a Specific Project

2.1.5.1. Request Breakdown

Listing the details for a project requires three requests:

A GET request to the project name in the projects resource.
A GET request to the resourcequotas subresource of the project namespace.
A GET request to the limitranges subresource of the project namespace.

These requests return the Project, ResourceQuotaList, and LimitRangeList configurations respectively for the project namespace.

2.1.5.2. GET Request to List the Project Configuration

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/projects

2.1.5.3. GET Request to List the ResourceQuotaList Configuration

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/resourcequotas

2.1.5.4. GET Request to List the LimitRangeList Configuration

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/limitranges

2.1.6. Deleting a Project

2.1.6.1. Request Breakdown

Deleting a project requires one request:

A DELETE request to the project namespace in the projects resource of the namespace.

The DELETE request returns a code: 200 and the project is deleted.

2.1.6.2. DELETE Request to Delete a Project

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/projects/{$PROJECT}

2.2. Service Accounts

2.2.1. Description of Resource

ServiceAccount binds together:

a name, understood by users, and perhaps by peripheral systems, for an identity
a principal that can be authenticated and authorized
a set of secrets

2.2.2. Creating a New Service Account

2.2.2.1. Request Breakdown

Creating a new service account requires one request:

A POST request to the serviceaccounts subresource of the namespace.

The POST request uses a ServiceAccount configuration in the request body.

2.2.2.2. POST Request to Create a New Service Account

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts

Request Body

apiVersion: v1
kind: ServiceAccount
metadata:
  name: {$SERVICEACCOUNT}

2.2.3. Listing All Service Accounts in an Environment

2.2.3.1. Request Breakdown

Listing all the service accounts in an environment requires one request:

A GET request to the serviceaccounts resource.

The GET request returns the ServiceAccountList, listing the details of all service accounts in the environment.

2.2.3.2. GET Request to Return All Service Accounts in an Environment

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/serviceaccounts

2.2.4. Listing all Service Accounts in a Namespace

2.2.4.1. Request Breakdown

Listing all the service accounts in a namespace requires one request:

A GET request to the serviceaccounts subresource of the namespace.

The GET request returns the ServiceAccountList, listing the details of all service accounts in the namespace.

2.2.4.2. GET Request to Return Service Accounts in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts

2.2.5. Listing a Specific Service Account Configuration

2.2.5.1. Request Breakdown

Listing a specific service account configuration requires one request:

A GET request to the service account name in the serviceaccounts subresource of the namespace.

The GET request returns the ServiceAccount configuration for the specified service account.

2.2.5.2. GET Request to Return Specific Service Account Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

2.2.6. Adding a Role to a Service Account

2.2.6.1. Request Breakdown

Adding a role to a service account requires two requests, where the second request type is dependent on the response of the first:

A GET request to the policybindings subresource of the namespace.
A POST request to the rolebindings subresource of the namespace (if the role has not been previously bound to an object in the namespace) +. OR
A PUT request to the role name in the rolebindings subresource of the namespace.

The GET request returns the PolicyBindingList, listing all the RoleBinding configurations in the namespace.

Create a RoleBinding with a POST request to bind an object to a role. Once the role binding exists in the namespace, binding another object to that role requires modification of the RoleBinding with a PUT request.

2.2.6.2. GET Request to Return PolicyBindingList in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/policybindings

The GET request returns a list of the role bindings that are present in the namespace.

Response Body Snippet

...
RoleBindings:
  name: {$ROLE}
  roleBinding:
    metadata:
      name: {$ROLE}
      namespace: {$PROJECT}
      uid: {$UID}
      resourceVersion: "{$VERSION_NUMBER}"
    roleRef:
      name: {$ROLE}
    subjects:
    - kind: ServiceAccount
      name: {$SERVICEACCOUNT}
      namespace: {$PROJECT}
    userNames:
    - system:serviceaccount:{$PROJECT}:{$SERVICEACCOUNT}
...

If the intended role is not listed, send a POST request to create the RoleBinding configuration. Include the service account as a subject for the role, and the system:serviceaccount:{$PROJECT}:{$SERVICEACCOUNT} user name that distinguishes the service account.

If the role is listed, as in the response in the example above, update the returned RoleBinding configuration with the subject and userName of the service account being added to the role and send it as a PUT request to the role name in the rolebindings subresource of the namespace.

2.2.6.3. POST Request to Create a RoleBinding in a Namespace

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/rolebindings

Request Body

kind: RoleBinding
metadata:
  name: {$ROLE}
  namespace: {$PROJECT}
roleRef:
  name: {$ROLE}
subjects:
- kind: ServiceAccount
  name: {$SERVICEACCOUNT}
  namespace: {$PROJECT}
userNames:
- system:serviceaccount:{$PROJECT}:{$SERVICEACCOUNT}

2.2.6.4. PUT Request to Add a Service Account to an Existing Role

Request Header

curl -k -v \
-X PUTv \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/rolebindings/{$ROLE}

Request Body

kind: RoleBinding
metadata:
  name: {$ROLE}
  namespace: {$PROJECT}
  uid: {$UID}
  resourceVersion: "{$VERSION_NUMBER}"
roleRef:
  name: {$ROLE}
subjects:
- kind: ServiceAccount
  name: {$SERVICEACCOUNT}
  namespace: {$PROJECT}
subjects:
- kind: ServiceAccount
  name: {$SERVICEACCOUNT-2}
  namespace: {$PROJECT}
userNames:
- system:serviceaccount:{$PROJECT}:{$SERVICEACCOUNT}
- system:serviceaccount:{$PROJECT}:{$SERVICEACCOUNT-2}

2.2.7. Linking a Secret to a Service Account

2.2.7.1. Request Breakdown

Linking a secret to a service account requires two requests:

A GET request to the service account name in the serviceaccounts subresource of the namespace.
A PUT request with updated secrets parameter to the service account name in the serviceaccounts subresource of the namespace.

The GET request returns the ServiceAccount configuration.

The PUT request uses the returned ServiceAccount configuration with an updated secrets parameter to include the secret to link to the service account.

2.2.7.2. GET Request to Return Service Account Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...

2.2.7.3. PUT Request to Add Secret to Service Account Configuration

Request Header

curl -k -v \
-X PUT  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
- name: {$SECRET_NAME}
...

2.2.8. Unlinking a Secret from a Service Account

2.2.8.1. Request Breakdown

Unlinking a secret from a service account requires two requests:

A GET request to the service account name in the serviceaccounts subresource of the namespace.
A PUT request with modified secrets parameter to the service account name in the serviceaccounts subresource of the namespace.

The GET request returns the ServiceAccount configuration.

The PUT request uses the returned ServiceAccount configuration with a modified secrets parameter to unlink the secret from the service account.

2.2.8.2. GET Request to Return Service Account Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
- name: {$SECRET_NAME}
...

2.2.8.3. PUT Request to Remove Secret from Service Account Configuration

Request Header

curl -k -v \
-X PUT  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...

2.2.9. Deleting a Service Account

2.2.9.1. Request Breakdown

Deleting a service account requires one request:

A DELETE request to the service account name in the serviceaccounts subresource of the namespace.

The DELETE request returns a code: 200 and the service account is deleted.

2.2.9.2. DELETE Request to Delete Service Account

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

2.3. Secrets

2.3.1. Description of Resource

The Secret resource type provides a mechanism to hold sensitive information such as passwords, OpenShift Container Platform client configuration files, dockercfg files, private source repository credentials, and so on. Secrets decouple sensitive content from the pods.

2.3.2. Creating Secrets from File

2.3.2.1. Request Breakdown

Creating a new secret requires one request:

A POST request to the secrets subresource of the namespace.

The POST request to the secret subresource uses a Secret configuration in the request body.

2.3.2.2. POST Request to Create a New Secret

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/secrets

Request Body

apiVersion: v1
kind: Secret
metadata:
  name: {$SECRET}
  namespace: {$PROJECT}
data:
  username: ZGVtby11c2Vy
  password: cGFzc3dvcmQ=
  ca.crt: {$BASE64-ENCODED-CERTIFICATE}
type: kubernetes.io/basic-auth

Table 2.1. data Parameter Descriptions
Parameter Name	Description	Additional Notes
`{$FILENAME}`	Base64-encoded contents of file, where the {$FILENAME} parameter is the plaintext file name	If the file is already encrypted, the `type` field for the secret needs a value of 'Opaque'. See the example secret configuration for an example.
`username`	Base64-encoded user name for basic authentication
`password`	Base64-encoded password for the supplied basic authentication user name
`ca.crt`	Base64-encoded contents of certificate file
`ssh-privatekey`	Base64-encoded contents of SSH private key file

2.3.3. Listing Secrets in an Environment

2.3.3.1. Request Breakdown

Listing all the secrets in an environment requires one request:

A GET request to the secrets resource.

The GET request to the secrets resource returns returns the SecretList, listing the details for all secrets in the environment.

2.3.3.2. GET Request to Return All Secrets in an Environment

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/secrets

2.3.4. Listing Secrets in a Namespace

2.3.4.1. Request Breakdown

Listing all the secrets in a namespace requires one request:

A GET request to the secrets subresource of the namespace.

The GET request to the secrets resource returns the SecretList, listing the details of all secrets in the namespace.

2.3.4.2. GET Request to Return Secrets in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/secrets

2.3.5. Listing a Specific Secret Configuration

2.3.5.1. Request Breakdown

Listing a specific secret configuration requires one request:

A GET request to the secret name in the secrets subresource of the namespace.

The GET request returns the Secret configuration for the specified secret.

2.3.5.2. GET Request to Return Specific Secret Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/secrets/{$SECRET}

2.3.6. Linking a Secret to a Service Account

2.3.6.1. Request Breakdown

Linking a secret to a service account requires two requests:

A GET request to the service account name in the serviceaccounts subresource of the namespace.
A PUT request with updated secrets parameter to the service account name in the serviceaccounts subresource of the namespace.

The GET request returns the ServiceAccount configuration.

The PUT request uses the returned ServiceAccount configuration with an updated secrets parameter to include the secret to link to the service account.

2.3.6.2. GET Request to Return Service Account Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...

2.3.6.3. PUT Request to Add Secret to Service Account Configuration

Request Header

curl -k -v \
-X PUT  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
- name: {$SECRET_NAME}
...

2.3.7. Unlinking a Secret from a Service Account

2.3.7.1. Request Breakdown

Unlinking a secret from a service account requires two requests:

A GET request to the service account name in the serviceaccounts subresource of the namespace.
A PUT request with modified secrets parameter to the service account name in the serviceaccounts subresource of the namespace.

The GET request returns the ServiceAccount configuration.

The PUT request uses the returned ServiceAccount configuration with a modified secrets parameter to unlink the secret from the service account.

2.3.7.2. GET Request to Return Service Account Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
- name: {$SECRET_NAME}
...

2.3.7.3. PUT Request to Remove Secret from Service Account Configuration

Request Header

curl -k -v \
-X PUT  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

Request Body Snippet

...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...

2.3.8. Deleting a Service Account

2.3.8.1. Request Breakdown

Deleting a service account requires one request:

A DELETE request to the service account name in the serviceaccounts subresource of the namespace.

The DELETE request returns a code: 200 and the service account is deleted.

2.3.8.2. DELETE Request to Delete Service Account

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/serviceaccounts/{$SERVICEACCOUNT}

2.3.9. Deleting Secrets

2.3.9.1. Request Breakdown

Deleting a secret requires one request:

A DELETE request to the secret name in the secret subresource of the namespace.

The *DELETE request returns a code: 200 and the secret is deleted.

2.3.9.2. DELETE Request to Delete Secret

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/secrets/{$SECRET}

2.4. Persistent Volumes

2.4.1. Description of Resource

PersistentVolume (PV) is a storage resource provisioned by an administrator. It is analogous to a node.

2.4.2. Creating a New Persistent Volume

2.4.2.1. Request Breakdown

Creating a new persistent volume requires one request:

A POST request to the persistentvolumes resource.

The POST request uses a PersistentVolume configuration in the request body.

2.4.2.2. POST Request to Create a Persistent Volume

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/persistentvolumes

Request Body

kind: PersistentVolume
metadata:
  name: {$VOLUME}
spec:
  capacity:
    storage: {$SIZE}Gi
  accessModes:
  - ReadWriteMany
  nfs:
    path: {$/STORAGE/FILE/PATH}
    server: {$STORAGE_SERVER_HOSTNAME}

2.4.3. Listing All Persistent Volumes in an Environment

2.4.3.1. Request Breakdown

Listing all the persistent volumes in an environment requires one request:

A GET request to the persistentvolumes resource.

The GET request returns returns the PersistentVolumeList, listing the details of all persistent volumes in the environment.

2.4.3.2. GET Request to Return All Persistent Volumes in an Environment

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/persistentvolumes

2.4.4. Listing a Specific Persistent Volume Configuration

2.4.4.1. Request Breakdown

Listing a specific persistent volumes configuration requires one request:

A GET request to the persistent volume name in the persistentvolumes resource.

The GET request returns the PersistentVolume configuration for the specified persistent volume.

2.4.4.2. GET Request to Return Specific Persistent Volume Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/persistentvolumes/{$VOLUME}

2.4.5. Deleting a Persistent Volume

2.4.5.1. Request Breakdown

Deleting a persistent volume requires one request:

A DELETE request to the persistent volume name in the persistentvolumes resource.

The DELETE request returns a code: 200 and the persistent volume is deleted.

2.4.5.2. DELETE Request to Delete Persistent Volume

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/persistentvolumes/{$VOLUME}

2.5. Persistent Volume Claims

2.5.1. Description of Resource

PersistentVolumeClaim is a user’s request for and claim to a persistent volume.

2.5.2. Creating a New Persistent Volume Claim

2.5.2.1. Request Breakdown

Creating a new persistent volume claim requires one request:

A POST request to the persistentvolumeclaims subresource of the namespace.

The POST request uses a PersistentVolumeClaim configuration in the request body.

2.5.2.2. POST Request to Create a Persistent Volume Claim

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/persistentvolumeclaims

Request Body

kind: PersistentVolumeClaim
metadata:
  name: {$CLAIM}
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: {$SIZE}Gi

2.5.3. Listing All Persistent Volume Claims in an Environment

2.5.3.1. Request Breakdown

Listing all the persistent volume claims in an environment requires one request:

A GET request to the persistentvolumeclaims resource.

The GET request returns the PersistentVolumeClaimList, listing the details of all persistent volume claims in the environment.

2.5.3.2. GET Request to Return All Persistent Volume Claims in an Environment

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/persistentvolumeclaims

2.5.4. Listing all Persistent Volume Claims in a Namespace

2.5.4.1. Request Breakdown

Listing all the persistent volume claims in a namespace requires one request:

A GET request to the persistentvolumeclaims subresource of the namespace.

The GET request returns the PersistentVolumeClaimList, listing the details of all persistent volume claims in the namespace.

2.5.4.2. GET Request to Return Persistent Volume Claims in Namespace

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/persistentvolumeclaims

2.5.5. Listing a Specific Persistent Volume Claim Configuration

2.5.5.1. Request Breakdown

Listing a specific persistent volume claim configuration requires one request:

A GET request to the persistent volume claim name in the persistentvolumeclaims subresource of the namespace.

The GET request returns the PersistentVolumeClaim configuration for the specified persistent volume claim.

2.5.5.2. GET Request to Return Specific Persistent Volume Claim Configuration

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/persistentvolumeclaims/{$CLAIM}

2.5.6. Adding a Persistent Volume Claim to an Object

Persistent volume claims can be added to objects that have a pod template: deploymentconfigs, replication controllers, and pods. However, you can not change a pod’s volumes once it has been created.

If you alter a volume setting on a deployment config, a deployment will be triggered. Changing a replication controller will not affect running pods.

Adding a persistent volume claim to an object configuration requires two requests:

A GET request to the object name in the {$OBJECT} subresource of the namespace.
A PATCH request with updated field values to the object name in the {$OBJECT} subresource of the namespace.

The GET request is optional as the PATCH request body is not determined by the returned configuration, however it can be useful for preparing the PATCH request body.

The syntax for the PATCH request is the same for both deploymentconfig and replicationcontroller objects.

2.5.6.1. PATCH Request to Add Persistent Volume Claim

Note

PATCH requests require JSON formatting.

The following PATCH request example adds a persistent volume claim {$CLAIM}, which is bound to persistent volume {$VOLUME), to deploymentconfig {$DEPLOYMENTCONFIG}. The same PATCH can be applied to a replicationcontroller object with modified target:

Request Header

curl -k -v \
-X PATCH \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: text/strategic-merge-patch+json" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/deploymentconfig/{$DEPLOYMENTCONFIG}

Request Body

{
    "spec": {
        "template": {
            "spec": {
                "volumes": [
                    {
                        "name": "{$VOLUME}",
                        "persistentVolumeClaim": {
                            "claimName": "{$CLAIM}"
                        }
                    }
                ]
            }
        }
    }
}

2.5.7. Removing a Persistent Volume Claim from an Object

If you alter a volume setting on a deployment config, a deployment will be triggered. Changing a replication controller will not affect running pods.

Removing a persistent volume claim from an object configuration requires two requests:

A GET request to the object name in the {$OBJECT} subresource of the namespace.
A PATCH request with a delete $patch type to the object name in the {$OBJECT} subresource of the namespace.

The GET request is optional as the PATCH request body is not determined by the returned configuration, however it can be useful for preparing the PATCH request body.

The syntax for the PATCH request is the same for both deploymentconfig and replicationcontroller objects.

2.5.7.1. PATCH Request to Add Persistent Volume Claim

Note

PATCH requests require JSON formatting.

Request Header

curl -k -v \
-X PATCH \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: text/strategic-merge-patch+json" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/deploymentconfig/{$DEPLOYMENTCONFIG}

Request Body

{
    "spec": {
        "template": {
            "spec": {
                "volumes": [
                    {
                        "$patch": "delete",
                        "name": "{$VOLUME}"
                    }
                ]
            }
        }
    }
}

2.5.8. Deleting a Persistent Volume Claim

2.5.8.1. Request Breakdown

Deleting a persistent volume claim requires one request:

A DELETE request to the persistent volume claim name in the persistentvolumeclaims subresource of the namespace.

The DELETE request returns a code: 200 and the persistent volume claim is deleted.

2.5.8.2. DELETE Request to Delete Persistent Volume Claim

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/persistentvolumeclaims/{$CLAIM}