Red Hat SummitThis documentation is for a release that is no longer maintained
See documentation for the latest supported version 3 or the latest supported version 4.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
projectsresource.
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
Request Body
apiVersion: v1
kind: Project
metadata:
name: {$PROJECT_NAME}
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
projectrequestsresource.
The POST request uses a ProjectRequest configuration in the request body.
2.1.3.2. POST Request to Create a New Project
Request Header
Request Body
apiVersion: v1
kind: ProjectRequest
metadata:
name: {$PROJECT_NAME}
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
projectsresource.
The GET request returns a ProjectList configuration.
2.1.4.2. GET Request to List all Projects
Request Header
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
projectsresource. -
A GET request to the
resourcequotassubresource of the project namespace. -
A GET request to the
limitrangessubresource 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
2.1.5.3. GET Request to List the ResourceQuotaList Configuration
Request Header
2.1.5.4. GET Request to List the LimitRangeList Configuration
Request Header
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
projectsresource 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
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
serviceaccountssubresource 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
Request Body
apiVersion: v1
kind: ServiceAccount
metadata:
name: {$SERVICEACCOUNT}
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
serviceaccountsresource.
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
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
serviceaccountssubresource 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
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
serviceaccountssubresource 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
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
policybindingssubresource of the namespace. -
A POST request to the
rolebindingssubresource 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
rolebindingssubresource 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
The GET request returns a list of the role bindings that are present in the namespace.
Response Body Snippet
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
Request Body
2.2.6.4. PUT Request to Add a Service Account to an Existing Role
Request Header
Request Body
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
serviceaccountssubresource of the namespace. -
A PUT request with updated
secretsparameter to the service account name in theserviceaccountssubresource 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
Request Body Snippet
...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...
...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...2.2.7.3. PUT Request to Add Secret to Service Account Configuration
Request Header
Request Body Snippet
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
serviceaccountssubresource of the namespace. -
A PUT request with modified
secretsparameter to the service account name in theserviceaccountssubresource 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
Request Body Snippet
2.2.8.3. PUT Request to Remove Secret from Service Account Configuration
Request Header
Request Body Snippet
...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...
...
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
serviceaccountssubresource 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
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
secretssubresource 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
Request Body
| Parameter Name | Description | Additional Notes |
|---|---|---|
|
| Base64-encoded contents of file, where the {$FILENAME} parameter is the plaintext file name |
If the file is already encrypted, the |
|
| Base64-encoded user name for basic authentication | |
|
| Base64-encoded password for the supplied basic authentication user name | |
|
| Base64-encoded contents of certificate file | |
|
| 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
secretsresource.
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
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
secretssubresource 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
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
secretssubresource 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
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
serviceaccountssubresource of the namespace. -
A PUT request with updated
secretsparameter to the service account name in theserviceaccountssubresource 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
Request Body Snippet
...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...
...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...2.3.6.3. PUT Request to Add Secret to Service Account Configuration
Request Header
Request Body Snippet
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
serviceaccountssubresource of the namespace. -
A PUT request with modified
secretsparameter to the service account name in theserviceaccountssubresource 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
Request Body Snippet
2.3.7.3. PUT Request to Remove Secret from Service Account Configuration
Request Header
Request Body Snippet
...
secrets:
- name: {$SERVICEACCOUNT}-token-x4tx5
- name: {$SERVICEACCOUNT}-dockercfg-7qfh6
...
...
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
serviceaccountssubresource 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
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
secretsubresource 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
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
persistentvolumesresource.
The POST request uses a PersistentVolume configuration in the request body.
2.4.2.2. POST Request to Create a Persistent Volume
Request Header
Request Body
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
persistentvolumesresource.
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
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
persistentvolumesresource.
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
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
persistentvolumesresource.
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
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
persistentvolumeclaimssubresource 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
Request Body
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
persistentvolumeclaimsresource.
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
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
persistentvolumeclaimssubresource 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
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
persistentvolumeclaimssubresource 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
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
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
Request Body
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$patchtype 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
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
Request Body
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
persistentvolumeclaimssubresource 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
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}