service accounts

_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 
 ---

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]

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]

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::[]

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/<deployment_config>
+----
+
+. Add the `serviceAccount` and `serviceAccountName` parameters to the `spec`
+field, and specify the service account that you want to use:
++
+----
+spec:
+  securityContext: {}
+  serviceAccount: <service_account>
+  serviceAccountName: <service_account>
+----

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 <serviceaccount-name> <secret-name>
+----
+
+To allow a secret to be mounted by a service account's pods, run:
+
+----
+$ oc secrets link --for=mount <serviceaccount-name> <secret-name>
+----
+
+[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:             <none>
+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
+----

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.
+
+|===

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 <service_account_name> <1>
+
+serviceaccount "robot" created
+----
+<1> To create a service account in a different project, specify `-n <project_name>`.
+
+. (Optional) View the secrets for the service account:
++
+[source,bash]
+----
+$ oc describe sa robot
+Name:		robot
+Namespace:	project1
+Labels:		<none>
+Annotations:	<none>
+
+Image pull secrets:	robot-dockercfg-qzbhb
+
+Mountable secrets: 	robot-token-f4khf
+                   	robot-dockercfg-qzbhb
+
+Tokens:            	robot-token-f4khf
+                   	robot-token-z8h44
+----

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::[]

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.

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.

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 `<serviceaccount_name>`
+
++
+[source,bash]
+----
+$ oc policy add-role-to-user <role_name> -z <serviceaccount_name>
+----
++
+[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
+----

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 <secret_name> \
+    --from-file=<file>.txt
+    
+secret/<secret_name>
+----
+
+. 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 <serviceaccount-name> <secret-name>
+----
+
+. To allow a secret to be mounted by a service account's pods, run:
++
+[source,bash]
+----
+$ oc secrets link --for=mount <serviceaccount-name> <secret-name>
+----
+
+. Confirm that the secret was added to the service account:
++
+[source,bash]
+----
+$ oc describe serviceaccount <serviceaccount-name> 
+Name:               <serviceaccount-name> 
+Labels:             <none>
+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.
+====
+////

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:<project>:<name>
+----
+
+Every service account is also a member of two groups:
+
+system:serviceaccounts:: Includes all service accounts in the system.
+system:serviceaccounts:<project>:: 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.

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 <secret-name>
+----
++
+For example:
++
+[source,bash]
+----
+$ oc describe secret robot-token-uzkbh -n top-secret
+
+Name:		robot-token-uzkbh
+Labels:		<none>
+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 <projectname>
+----
+
+. Confirm that you logged in as the service account:
++
+[source,bash]
+----
+$ oc whoami
+
+system:serviceaccount:top-secret:robot
+----

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"
+----