diff --git a/_topic_map.yml b/_topic_map.yml index ab5d7df92e..b87b9a36b2 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -59,6 +59,10 @@ Topics: File: using-rbac - Name: Configuring the user agent File: configuring-user-agent +- Name: Understanding and creating service accounts + File: understanding-and-creating-service-accounts +- Name: Using service accounts in applications + File: using-service-accounts-in-applications - Name: Using a service account as an OAuth client File: using-service-accounts-as-oauth-client --- diff --git a/authentication/understanding-and-creating-service-accounts.adoc b/authentication/understanding-and-creating-service-accounts.adoc new file mode 100644 index 0000000000..36b8b8f514 --- /dev/null +++ b/authentication/understanding-and-creating-service-accounts.adoc @@ -0,0 +1,19 @@ +[id='understanding-and-creating-service-accounts'] += Understanding and creating service accounts +include::modules/common-attributes.adoc[] +:context: understanding-service-accounts +toc::[] + +include::modules/service-accounts-overview.adoc[leveloffset=+1] + +include::modules/service-accounts-dedicated-admin-role.adoc[leveloffset=+1] + +include::modules/dedicated-admin-role-overview.adoc[leveloffset=+1] + +include::modules/service-accounts-enabling-authentication.adoc[leveloffset=+1] + +include::modules/service-accounts-creating.adoc[leveloffset=+1] + +include::modules/service-accounts-configuration-parameters.adoc[leveloffset=+1] + +include::modules/service-accounts-granting-roles.adoc[leveloffset=+1] diff --git a/authentication/using-service-accounts-in-applications.adoc b/authentication/using-service-accounts-in-applications.adoc new file mode 100644 index 0000000000..952ebdff84 --- /dev/null +++ b/authentication/using-service-accounts-in-applications.adoc @@ -0,0 +1,15 @@ +[id='using-service-accounts'] += Using service accounts in applications +include::modules/common-attributes.adoc[] +:context: using-service-accounts +toc::[] + +include::modules/service-accounts-overview.adoc[leveloffset=+1] + +include::modules/service-accounts-default.adoc[leveloffset=+1] + +include::modules/service-accounts-creating.adoc[leveloffset=+1] + +include::modules/service-accounts-using-credentials-inside-a-container.adoc[leveloffset=+1] + +include::modules/service-accounts-using-credentials-externally.adoc[leveloffset=+1] diff --git a/modules/dedicated-admin-role-overview.adoc b/modules/dedicated-admin-role-overview.adoc new file mode 100644 index 0000000000..f683cfdcb2 --- /dev/null +++ b/modules/dedicated-admin-role-overview.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='dedicated-admin-role-overview-{context}'] +ifdef::openshift-dedicated[] += About the dedicated administrator role + +The accounts for dedicated administrators of an {product-title} cluster, +have increased +permissions and access to all user-created projects. + +//// +[NOTE] +==== +Some configuration changes or procedures discussed in this guide can be +performed by only the {product-title} Operations Team. They are included in this +guide for informational purposes to help you as an {product-title} cluster +administrator better understand what configuration options are possible. If you +want to request a change to your cluster that you cannot perform using the +administrator CLI, open a support case on the +https://access.redhat.com/support/[Red Hat Customer Portal]. +==== +//// + +When your account has the `dedicated-cluster-admin` authorization role +bound to it, you +are automatically bound to the `dedicated-project-admin` role for any new projects +that users in the cluster create. + +You can perform actions that are associated with a set of verbs, such as `create`, +to operate on a set of resource names, such as `templates`. To view the details +of these roles and their sets of +verbs and resources, run the following commands: + +---- +$ oc describe clusterrole/dedicated-cluster-admin +$ oc describe clusterrole/dedicated-project-admin +---- + +The verb names do not necessarily all map directly to `oc` commands but rather +equate more generally to the types of CLI operations you can perform. For +example, having the `list` verb means that you can display a list of all objects +of a given resource name by running the `oc get` command, but the `get` verb +means that you can display the details of a specific object if you know its name +by runnign the `oc describe` command. + +{product-title} administrators can grant users a `dedicated-reader` role, which +provides view-only access at the cluster level and view access for all +user projects. + +endif::[] diff --git a/modules/pod-using-a-different-service-account.adoc b/modules/pod-using-a-different-service-account.adoc new file mode 100644 index 0000000000..08a2a24f4f --- /dev/null +++ b/modules/pod-using-a-different-service-account.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * + +[id='pod-using-a-different-service-account-{context}'] += Running a pod with a different service account + +You can run a pod with a service account other than the default: + +.Prerequisites + +* Install the `oc` command line interface. +* Configure a service account. +* Create a deployment configuration. + +.Procedure + +. Edit the deployment configuration: ++ +---- +$ oc edit dc/ +---- + +. Add the `serviceAccount` and `serviceAccountName` parameters to the `spec` +field, and specify the service account that you want to use: ++ +---- +spec: + securityContext: {} + serviceAccount: + serviceAccountName: +---- diff --git a/modules/service-accounts-adding-secrets.adoc b/modules/service-accounts-adding-secrets.adoc new file mode 100644 index 0000000000..87596035b1 --- /dev/null +++ b/modules/service-accounts-adding-secrets.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-managing-secrets-{context}'] +== Managing secrets on a service account's pod + +In addition to providing API credentials, a pod's service account determines +which secrets the pod is allowed to use. + +Pods use secrets in two ways: + +* image pull secrets, providing credentials used to pull images for the pod's containers +* mountable secrets, injecting the contents of secrets into containers as files + +To allow a secret to be used as an image pull secret by a service account's +pods, run: + +---- +$ oc secrets link --for=pull +---- + +To allow a secret to be mounted by a service account's pods, run: + +---- +$ oc secrets link --for=mount +---- + +[NOTE] +==== +Limiting secrets to only the service accounts that reference them is disabled by +default. This means that if `serviceAccountConfig.limitSecretReferences` is set +to `false` (the default setting) in the master configuration file, mounting +secrets to a service account's pods with the `--for=mount` option is not +required. However, using the `--for=pull` option to enable using an image pull +secret is required, regardless of the +`serviceAccountConfig.limitSecretReferences` value. +==== + +This example creates and adds secrets to a service account: + +---- +$ oc create secret generic secret-plans \ + --from-file=plan1.txt \ + --from-file=plan2.txt +secret/secret-plans + +$ oc create secret docker-registry my-pull-secret \ + --docker-username=mastermind \ + --docker-password=12345 \ + --docker-email=mastermind@example.com +secret/my-pull-secret + +$ oc secrets link robot secret-plans --for=mount + +$ oc secrets link robot my-pull-secret --for=pull + +$ oc describe serviceaccount robot +Name: robot +Labels: +Image pull secrets: robot-dockercfg-624cx + my-pull-secret + +Mountable secrets: robot-token-uzkbh + robot-dockercfg-624cx + secret-plans + +Tokens: robot-token-8bhpp + robot-token-uzkbh +---- diff --git a/modules/service-accounts-configuration-parameters.adoc b/modules/service-accounts-configuration-parameters.adoc new file mode 100644 index 0000000000..0c6e68d324 --- /dev/null +++ b/modules/service-accounts-configuration-parameters.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-configuration-parameters-{context}'] += Service account configuration parameters + +You can provide values for the following service account parameters in the +*_/etc/origin/master/master-config.yml_* file on the master host. + +.Service account configuration parameters +[cols="3a,3a,6a",options="header"] +|=== + +| Parameter Name | Type | Description + +|`LimitSecretReferences` +|Boolean +|Controls whether or not to allow a service account to reference any secret in a +namespace without explicitly referencing them. + +|`ManagedNames` +|String +|A list of service account names that is automatically created in each namespace. +If no names are specified, the `ServiceAccountsController` service does not +start. + +|`MasterCA` +|String +|The CA that verifies the TLS connection back to the master. The service account +controller automatically injects the contents of this file into pods so they +can verify connections to the master. + +|`PrivateKeyFile` +|String +|A file that contains a PEM-encoded private RSA key, which is used to sign +service account tokens. If no private key is specified, the service account +`TokensController` service does not start. + +|`PublicKeyFiles` +|String +|A list of files, each of which contains a PEM-encoded public RSA key. If any file +contains a private key, the public portion of the key is used. The list of +public keys is used to verify presented service account tokens. Each key is +tried in order until the list is exhausted or verification succeeds. If no keys +are specified, no service account authentication is available. + +|`ServiceAccountConfig` +|List +|The parameter that contains the other listed service account parameters. + +|=== diff --git a/modules/service-accounts-creating.adoc b/modules/service-accounts-creating.adoc new file mode 100644 index 0000000000..fe7ca46257 --- /dev/null +++ b/modules/service-accounts-creating.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-managing-{context}'] += Creating service accounts + +You can create a service account in a project and grant it permissions by +binding it to a role. + +.Procedure + +. (Optional) To view the service accounts in the current project: ++ +[source,bash] +---- +$ oc get sa + +NAME SECRETS AGE +builder 2 2d +default 2 2d +deployer 2 2d +---- + +. To create a new service account in the current project: ++ +[source,bash] +---- +$ oc create sa <1> + +serviceaccount "robot" created +---- +<1> To create a service account in a different project, specify `-n `. + +. (Optional) View the secrets for the service account: ++ +[source,bash] +---- +$ oc describe sa robot +Name: robot +Namespace: project1 +Labels: +Annotations: + +Image pull secrets: robot-dockercfg-qzbhb + +Mountable secrets: robot-token-f4khf + robot-dockercfg-qzbhb + +Tokens: robot-token-f4khf + robot-token-z8h44 +---- diff --git a/modules/service-accounts-dedicated-admin-role.adoc b/modules/service-accounts-dedicated-admin-role.adoc new file mode 100644 index 0000000000..31b3e3c5a0 --- /dev/null +++ b/modules/service-accounts-dedicated-admin-role.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + + +[id='service-accounts-dedicated-admin-role-{context}'] +ifdef::openshift-dedicated[] += Service accounts in {product-title} + +As an {product-title} administrator, you can use service accounts to perform any +actions that require {product-title} `admin` roles. + +The `dedicated-admin` service creates the `dedicated-admins` group. This group +is granted the roles at the cluster or individual project +level. Users can be assigned to this group, and group membership defines who has +{product-title} administrator access. However, by design, service accounts +cannot be added to regular groups. + +Instead, the `dedicated-admin` service creates a special project for this +purpose named `dedicated-admin`. The service account group for this project is +granted {product-title} `admin` roles, which grants {product-title} administrator +access to all service accounts within the `dedicated-admin` project. You can +then use these service accounts to perform any actions that require +{product-title} administrator access. + +Users that are members of the `dedicated-admins` group are granted the +`dedicated-admin` role permissions and have `edit` access to the `dedicated-admin` +project. These users can manage the service accounts in this project +and create new ones as needed. + +Users with a `dedicated-reader` role are granted edit and view access to the +`dedicated-reader` project and view-only access to the other projects. +endif::[] diff --git a/modules/service-accounts-default.adoc b/modules/service-accounts-default.adoc new file mode 100644 index 0000000000..f1f76cd144 --- /dev/null +++ b/modules/service-accounts-default.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-default-{context}'] += Default service accounts + +Your {product-title} cluster contains default service accounts for +cluster management and generates more service accounts for each project. + +[id='default-cluster-service-accounts{context}'] +== Default cluster service accounts + +Several infrastructure controllers run using service account credentials. The +following service accounts are created in the {product-title} infrastructure +project (`openshift-infra`) at server start, and given the following roles +cluster-wide: + +[cols="1,3",options="header"] +|==== +|Service Account |Description + +|`replication-controller` +|Assigned the `system:replication-controller` role + +|`deployment-controller` +|Assigned the `system:deployment-controller` role + +|`build-controller` +|Assigned the `system:build-controller` role. Additionally, the +`build-controller` service account is included in the privileged +security context constraint in order to create privileged +build pods. +|==== + + +//// +To configure the project where those service accounts are created, set the +`openshiftInfrastructureNamespace` field in the +*_/etc/origin/master/master-config.yml_* file on the master: + +---- +policyConfig: + ... + openshiftInfrastructureNamespace: openshift-infra +---- +//// + +[[default-service-accounts-and-roles]] +== Default project service accounts and roles + +Three service accounts are automatically created in each project: + +[options="header",cols="1,3"] +|=== +|Service Account |Usage + +|`builder` +|Used by build pods. It is given the `system:image-builder` role, which allows +pushing images to any image stream in the project using the internal Docker +registry. + +|`deployer` +|Used by deployment pods and given the `system:deployer` role, which allows +viewing and modifying replication controllers and pods in the project. + +|`default` +|Used to run all other pods unless they specify a different service account. +|=== + +All service accounts in a project are given the `system:image-puller` role, +which allows pulling images from any image stream in the project using the +internal container image registry. diff --git a/modules/service-accounts-enabling-authentication.adoc b/modules/service-accounts-enabling-authentication.adoc new file mode 100644 index 0000000000..618f22363f --- /dev/null +++ b/modules/service-accounts-enabling-authentication.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-enabling-authentication-{context}'] += Enabling service account authentication + +Service accounts authenticate to the API using tokens signed by a private RSA +key. The authentication layer verifies the signature using a matching public RSA +key. + +.Procedure + +* To enable service account token generation, update the `*serviceAccountConfig*` +stanza in the *_/etc/origin/master/master-config.yml_* file on the master to +specify a `*privateKeyFile*` (for signing), and a matching public key file in +the `*publicKeyFiles*` list: ++ +[source,yaml] +---- +serviceAccountConfig: + ... + masterCA: ca.crt <1> + privateKeyFile: serviceaccounts.private.key <2> + publicKeyFiles: + - serviceaccounts.public.key <3> + - ... +---- +<1> CA file to validate the API server's serving certificate. +<2> Private RSA key file for token signing. +<3> Public RSA key files for token verification. If you provide private key +files, then the public key component is used. You can specify multiple public +key files, and a token is accepted if it can be validated by one of the +public keys. This allows rotation of the signing key while still accepting +tokens generated by the previous signer. diff --git a/modules/service-accounts-granting-roles.adoc b/modules/service-accounts-granting-roles.adoc new file mode 100644 index 0000000000..7c015a5585 --- /dev/null +++ b/modules/service-accounts-granting-roles.adoc @@ -0,0 +1,53 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-granting-roles-{context}'] += Examples of granting roles to service accounts + +You can grant roles to service accounts in the same way that you grant roles +to a regular user account. + +* You can modify the service accounts for the current project. For example, to add +the `view` role to the `robot` service account in the `top-secret` project: ++ +[source,bash] +---- +$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot +---- + +* You can also grant access to a specific service account in a project. For +example, from the project to which the service account belongs, use +the `-z` flag and specify the `` + ++ +[source,bash] +---- +$ oc policy add-role-to-user -z +---- ++ +[IMPORTANT] +==== +If you want to grant access to a specific service account in a project, use the +`-z` flag. Using this flag helps prevent typos and ensures that access +is granted to only the specified service account. +==== + +* To modify a different namespace, you can use the `-n` option to indicate the +project namespace it applies to, as shown in the following examples. + +** For example, to allow all service accounts in all projects to view resources in +the `top-secret` project: ++ +[source,bash] +---- +$ oc policy add-role-to-group view system:serviceaccounts -n top-secret +---- + +** To allow all service accounts in the `managers` project to edit resources in the +`top-secret` project: ++ +[source,bash] +---- +$ oc policy add-role-to-group edit system:serviceaccounts:managers -n top-secret +---- diff --git a/modules/service-accounts-managing-secrets.adoc b/modules/service-accounts-managing-secrets.adoc new file mode 100644 index 0000000000..22551f0282 --- /dev/null +++ b/modules/service-accounts-managing-secrets.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-managing-secrets-{context}'] += Managing allowed secrets + +You can use the service account's secrets in your application's pods for: + +* Image pull secrets, providing credentials used to pull images for the pod's containers +* Mountable secrets, injecting the contents of secrets into containers as files + +.Procedure + +. Create a secret: ++ +[source,bash] +---- +$ oc create secret generic \ + --from-file=.txt + +secret/ +---- + +. To allow a secret to be used as an image pull secret by a service account's +pods, run: ++ +[source,bash] +---- +$ oc secrets link --for=pull +---- + +. To allow a secret to be mounted by a service account's pods, run: ++ +[source,bash] +---- +$ oc secrets link --for=mount +---- + +. Confirm that the secret was added to the service account: ++ +[source,bash] +---- +$ oc describe serviceaccount +Name: +Labels: +Image pull secrets: robot-dockercfg-624cx + my-pull-secret + +Mountable secrets: robot-token-uzkbh + robot-dockercfg-624cx + secret-plans + +Tokens: robot-token-8bhpp + robot-token-uzkbh +---- + +//// +[NOTE] +==== +Limiting secrets to only the service accounts that reference them is disabled by +default. This means that if `serviceAccountConfig.limitSecretReferences` is set +to `false` (the default setting) in the master configuration file, mounting +secrets to a service account's pods with the `--for=mount` option is not +required. However, using the `--for=pull` option to enable using an image pull +secret is required, regardless of the +`serviceAccountConfig.limitSecretReferences` value. +==== +//// diff --git a/modules/service-accounts-overview.adoc b/modules/service-accounts-overview.adoc new file mode 100644 index 0000000000..e9f2869f38 --- /dev/null +++ b/modules/service-accounts-overview.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-overview-{context}'] += Service accounts overview + +A service account is an {product-title} account that allows a component to +directly access the API. Service accounts are API objects that exist within each project. +Service accounts provide a flexible way to control API +access without sharing a regular user's credentials. + +When you use the {product-title} CLI or web console, your API token +authenticates you to the API. You can associate a component with a service account +so that they can access the API without using a regular user's credentials. +ifdef::openshift-online,openshift-origin,openshift-dedicated,openshift-enterprise[] +For example, service accounts can allow: + +* Replication controllers to make API calls to create or delete pods. +* Applications inside containers to make API calls for discovery purposes. +* External applications to make API calls for monitoring or integration purposes. +endif::[] + +Each service account's user name is derived from its project and name: + +---- +system:serviceaccount:: +---- + +Every service account is also a member of two groups: + +system:serviceaccounts:: Includes all service accounts in the system. +system:serviceaccounts::: Includes all service accounts in the +specified project. + +Each service account automatically contains two secrets: + +* An API token +* Credentials for the OpenShift Container Registry + +The generated API token and registry credentials do not expire, but you can +revoke them by deleting the secret. When you delete the secret, a new one is +automatically generated to take its place. diff --git a/modules/service-accounts-using-credentials-externally.adoc b/modules/service-accounts-using-credentials-externally.adoc new file mode 100644 index 0000000000..8a727b3ef5 --- /dev/null +++ b/modules/service-accounts-using-credentials-externally.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-using-credentials-externally-{context}'] += Using a service account's credentials externally + +You can distribute a service account's token to external applications that need to +authenticate to the API. + +In order to pull an image, the authenticated user must have `get` rights on the +requested `imagestreams/layers`. In order to push an image, the authenticated +user must have `update` rights on the requested `imagestreams/layers`. + +By default, all service accounts in a project have rights to pull any image in +the same project, and the *builder* service account has rights to push any image +in the same project. + +.Procedure + +. View the service account's API token: ++ +[source,bash] +---- +$ oc describe secret +---- ++ +For example: ++ +[source,bash] +---- +$ oc describe secret robot-token-uzkbh -n top-secret + +Name: robot-token-uzkbh +Labels: +Annotations: kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe + +Type: kubernetes.io/service-account-token + +Data + +token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... +---- + +. Log in using the token that you obtained: ++ +[source,bash] +---- +$ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... + +Logged into "https://server:8443" as "system:serviceaccount:top-secret:robot" using the token provided. + +You don't have any projects. You can try to create a new project, by running + + $ oc new-project +---- + +. Confirm that you logged in as the service account: ++ +[source,bash] +---- +$ oc whoami + +system:serviceaccount:top-secret:robot +---- diff --git a/modules/service-accounts-using-credentials-inside-a-container.adoc b/modules/service-accounts-using-credentials-inside-a-container.adoc new file mode 100644 index 0000000000..35af4cfb3e --- /dev/null +++ b/modules/service-accounts-using-credentials-inside-a-container.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * authentication/using-service-accounts.adoc + +[id='service-accounts-using-credentials-inside-a-container-{context}'] += Using a service account's credentials inside a container + +When a pod is created, it specifies a service account (or uses the default +service account), and is allowed to use that service account's API credentials +and referenced secrets. + +.Procedure + +. View the API token for the pod's service account in the + *_/var/run/secrets/kubernetes.io/serviceaccount/token_* file. + +. Set the token value to the `Token` variable: ++ +[source,bash] +---- +$ TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" +---- + +. Use the token to to make API calls as the pod's service account. For example, +call the `users/~` API to get information about the user identified +by the token: ++ +[source,bash] +---- +$ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \ + "https://openshift.default.svc.cluster.local/oapi/v1/users/~" \ + -H "Authorization: Bearer $TOKEN" + +kind: "User" +apiVersion: "user.openshift.io/v1" +metadata: + name: "system:serviceaccount:top-secret:robot" + selflink: "/oapi/v1/users/system:serviceaccount:top-secret:robot" + creationTimestamp: null +identities: null +groups: + - "system:serviceaccounts" + - "system:serviceaccounts:top-secret" +----