Other API Objects - Additional Concepts | Architecture

LimitRange
ResourceQuota
Resource
Secret
PersistentVolume
PersistentVolumeClaim
OAuth Objects
User Objects

LimitRange

A limit range provides a mechanism to enforce min/max limits placed on resources in a Kubernetes namespace.

By adding a limit range to your namespace, you can enforce the minimum and maximum amount of CPU and Memory consumed by an individual pod or container.

See the Kubernetes documentation for more information.

ResourceQuota

Kubernetes can limit both the number of objects created in a namespace, and the total amount of resources requested across objects in a namespace. This facilitates sharing of a single Kubernetes cluster by several teams, each in a namespace, as a mechanism of preventing one team from starving another team of cluster resources.

See the Developer’s Guide and Kubernetes documentation for more information on ResourceQuota.

Resource

A Kubernetes Resource is something that can be requested by, allocated to, or consumed by a pod or container. Examples include memory (RAM), CPU, disk-time, and network bandwidth.

See the Developer’s Guide and Kubernetes documentation for more information.

Secret

Secrets are storage for sensitive information, such as keys, passwords, and certificates. They are accessible by the intended pod(s), but held separately from their definitions.

PersistentVolume

A persistent volume is an object (PersistentVolume) in the infrastructure provisioned by the cluster administrator. Persistent volumes provide durable storage for stateful applications.

See the Kubernetes documentation for more information.

PersistentVolumeClaim

A PersistentVolumeClaim object is a request for storage by a pod author. Kubernetes matches the claim against the pool of available volumes and binds them together. The claim is then used as a volume by a pod. Kubernetes makes sure the volume is available on the same node as the pod that requires it.

See the Kubernetes documentation for more information.

OAuth Objects

OAuthClient

An OAuthClient represents an OAuth client, as described in RFC 6749, section 2.

The following OAuthClient objects are automatically created:

`openshift-web-console`	Client used to request tokens for the web console
`openshift-browser-client`	Client used to request tokens at /oauth/token/request with a user-agent that can handle interactive logins
`openshift-challenging-client`	Client used to request tokens with a user-agent that can handle WWW-Authenticate challenges

Example 1. OAuthClient Object Definition

{
  "kind": "OAuthClient",
  "apiVersion": "v1",
  "metadata": {
    "name": "openshift-web-console", (1)
    "selfLink": "/osapi/v1/oAuthClients/openshift-web-console",
    "resourceVersion": "1",
    "creationTimestamp": "2015-01-01T01:01:01Z"
  },
  "respondWithChallenges": false, (2)
  "secret": "45e27750-a8aa-11e4-b2ea-3c970e4b7ffe", (3)
  "redirectURIs": [
    "https://localhost:8443" (4)
  ]
}

1	The `name` is used as the `client_id` parameter in OAuth requests.
2	When `respondWithChallenges` is set to `true`, unauthenticated requests to `/oauth/authorize` will result in `WWW-Authenticate` challenges, if supported by the configured authentication methods.
3	The value in the `secret` parameter is used as the `client_secret` parameter in an authorization code flow.
4	One or more absolute URIs can be placed in the `redirectURIs` section. The `redirect_uri` parameter sent with authorization requests must be prefixed by one of the specified `redirectURIs`.

OAuthClientAuthorization

An OAuthClientAuthorization represents an approval by a User for a particular OAuthClient to be given an OAuthAccessToken with particular scopes.

Creation of OAuthClientAuthorization objects is done during an authorization request to the OAuth server.

Example 2. OAuthClientAuthorization Object Definition

{
  "kind": "OAuthClientAuthorization",
  "apiVersion": "v1",
  "metadata": {
    "name": "bob:openshift-web-console",
    "resourceVersion": "1",
    "creationTimestamp": "2015-01-01T01:01:01-00:00"
  },
  "clientName": "openshift-web-console",
  "userName": "bob",
  "userUID": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe"
  "scopes": []
}

OAuthAuthorizeToken

An OAuthAuthorizeToken represents an OAuth authorization code, as described in RFC 6749, section 1.3.1.

An OAuthAuthorizeToken is created by a request to the /oauth/authorize endpoint, as described in RFC 6749, section 4.1.1.

An OAuthAuthorizeToken can then be used to obtain an OAuthAccessToken with a request to the /oauth/token endpoint, as described in RFC 6749, section 4.1.3.

Example 3. OAuthAuthorizeToken Object Definition

{
  "kind": "OAuthAuthorizeToken",
  "apiVersion": "v1",
  "metadata": {
    "name": "MDAwYjM5YjMtMzM1MC00NDY4LTkxODItOTA2OTE2YzE0M2Fj", (1)
    "resourceVersion": "1",
    "creationTimestamp": "2015-01-01T01:01:01-00:00"
  },
  "clientName": "openshift-web-console", (2)
  "expiresIn": 300, (3)
  "scopes": [],
  "redirectURI": "https://localhost:8443/console/oauth", (4)
  "userName": "bob", (5)
  "userUID": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe" (6)
}

1	`name` represents the token name, used as an authorization code to exchange for an OAuthAccessToken.
2	The `clientName` value is the OAuthClient that requested this token.
3	The `expiresIn` value is the expiration in seconds from the creationTimestamp.
4	The `redirectURI` value is the location where the user was redirected to during the authorization flow that resulted in this token.
5	`userName` represents the name of the User this token allows obtaining an OAuthAccessToken for.
6	`userUID` represents the UID of the User this token allows obtaining an OAuthAccessToken for.

OAuthAccessToken

An OAuthAccessToken represents an OAuth access token, as described in RFC 6749, section 1.4.

An OAuthAccessToken is created by a request to the /oauth/token endpoint, as described in RFC 6749, section 4.1.3.

Access tokens are used as bearer tokens to authenticate to the API.

Example 4. OAuthAccessToken Object Definition

{
  "kind": "OAuthAccessToken",
  "apiVersion": "v1",
  "metadata": {
    "name": "ODliOGE5ZmMtYzczYi00Nzk1LTg4MGEtNzQyZmUxZmUwY2Vh", (1)
    "resourceVersion": "1",
    "creationTimestamp": "2015-01-01T01:01:02-00:00"
  },
  "clientName": "openshift-web-console", (2)
  "expiresIn": 86400, (3)
  "scopes": [],
  "redirectURI": "https://localhost:8443/console/oauth", (4)
  "userName": "bob", (5)
  "userUID": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe", (6)
  "authorizeToken": "MDAwYjM5YjMtMzM1MC00NDY4LTkxODItOTA2OTE2YzE0M2Fj" (7)
}

1	`name` is the token name, which is used as a bearer token to authenticate to the API.
2	The `clientName` value is the OAuthClient that requested this token.
3	The `expiresIn` value is the expiration in seconds from the creationTimestamp.
4	The `redirectURI` is where the user was redirected to during the authorization flow that resulted in this token.
5	`userName` represents the User this token allows authentication as.
6	`userUID` represents the User this token allows authentication as.
7	`authorizeToken` is the name of the OAuthAuthorizationToken used to obtain this token, if any.

User Objects

Identity

When a user logs into OpenShift, they do so using a configured identity provider. This determines the user’s identity, and provides that information to OpenShift.

OpenShift then looks for a UserIdentityMapping for that Identity:

If the Identity already exists, but is not mapped to a User, login fails.
If the Identity already exists, and is mapped to a User, the user is given an OAuthAccessToken for the mapped User.
If the Identity does not exist, an Identity, User, and UserIdentityMapping are created, and the user is given an OAuthAccessToken for the mapped User.

Example 5. Identity Object Definition

{
    "kind": "Identity",
    "apiVersion": "v1",
    "metadata": {
        "name": "anypassword:bob", (1)
        "uid": "9316ebad-0fde-11e5-97a1-3c970e4b7ffe",
        "resourceVersion": "1",
        "creationTimestamp": "2015-01-01T01:01:01-00:00"
    },
    "providerName": "anypassword", (2)
    "providerUserName": "bob", (3)
    "user": {
        "name": "bob", (4)
        "uid": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe" (5)
    }
}

1	The identity name must be in the form providerName:providerUserName.
2	`providerName` is the name of the identity provider.
3	`providerUserName` is the name that uniquely represents this identity in the scope of the identity provider.
4	The `name` in the `user` parameter is the name of the user this identity maps to.
5	The `uid` represents the UID of the user this identity maps to.

User

A User represents an actor in the system. Users are granted permissions by adding roles to users or to their groups.

User objects are created automatically on first login, or can be created via the API.

Example 6. User Object Definition

{
  "kind": "User",
  "apiVersion": "v1",
  "metadata": {
    "name": "bob", (1)
    "uid": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe",
    "resourceVersion": "1",
    "creationTimestamp": "2015-01-01T01:01:01-00:00"
  },
  "identities": [
    "anypassword:bob" (2)
  ],
  "fullName": "Bob User" (3)
}

1	`name` is the user name used when adding roles to a user.
2	The values in `identities` are Identity objects that map to this user. May be `null` or empty for users that cannot log in.
3	The `fullName` value is an optional display name of user.

UserIdentityMapping

A UserIdentityMapping maps an Identity to a User.

Creating, updating, or deleting a UserIdentityMapping modifies the corresponding fields in the Identity and User objects.

An Identity can only map to a single User, so logging in as a particular identity unambiguously determines the User.

A User can have multiple identities mapped to it. This allows multiple login methods to identify the same User.

Example 7. UserIdentityMapping Object Definition

{
    "kind": "UserIdentityMapping",
    "apiVersion": "v1",
    "metadata": {
        "name": "anypassword:bob", (1)
        "uid": "9316ebad-0fde-11e5-97a1-3c970e4b7ffe",
        "resourceVersion": "1"
    },
    "identity": {
        "name": "anypassword:bob",
        "uid": "9316ebad-0fde-11e5-97a1-3c970e4b7ffe"
    },
    "user": {
        "name": "bob",
        "uid": "9311ac33-0fde-11e5-97a1-3c970e4b7ffe"
    }
}

1	`UserIdentityMapping` name matches the mapped `Identity` name

Group

A Group represents a list of users in the system. Groups are granted permissions by adding roles to users or to their groups.

Example 8. Group Object Definition

{
  "kind": "Group",
  "apiVersion": "v1",
  "metadata": {
    "name": "developers", (1)
    "creationTimestamp": "2015-01-01T01:01:01-00:00"
  },
  "users": [
    "bob" (2)
  ]
}

1	`name` is the group name used when adding roles to a group.
2	The values in `users` are the names of User objects that are members of this group.