Skip to content

Commit f09d774

Browse files
kalexand-rhkalexand-rh
authored
Merge pull request #13010 from kalexand-rh/osdocs-56
service accounts
2 parents dbcdbe6 + ddebc3f commit f09d774

16 files changed

+711
-0
lines changed

‎_topic_map.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ Topics:
5959
File: using-rbac
6060
- Name: Configuring the user agent
6161
File: configuring-user-agent
62+
- Name: Understanding and creating service accounts
63+
File: understanding-and-creating-service-accounts
64+
- Name: Using service accounts in applications
65+
File: using-service-accounts-in-applications
6266
- Name: Using a service account as an OAuth client
6367
File: using-service-accounts-as-oauth-client
6468
---

‎authentication/understanding-and-creating-service-accounts.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[id='understanding-and-creating-service-accounts']
2+
= Understanding and creating service accounts
3+
include::modules/common-attributes.adoc[]
4+
:context: understanding-service-accounts
5+
toc::[]
6+
7+
include::modules/service-accounts-overview.adoc[leveloffset=+1]
8+
9+
include::modules/service-accounts-dedicated-admin-role.adoc[leveloffset=+1]
10+
11+
include::modules/dedicated-admin-role-overview.adoc[leveloffset=+1]
12+
13+
include::modules/service-accounts-enabling-authentication.adoc[leveloffset=+1]
14+
15+
include::modules/service-accounts-creating.adoc[leveloffset=+1]
16+
17+
include::modules/service-accounts-configuration-parameters.adoc[leveloffset=+1]
18+
19+
include::modules/service-accounts-granting-roles.adoc[leveloffset=+1]

‎authentication/using-service-accounts-in-applications.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
[id='using-service-accounts']
2+
= Using service accounts in applications
3+
include::modules/common-attributes.adoc[]
4+
:context: using-service-accounts
5+
toc::[]
6+
7+
include::modules/service-accounts-overview.adoc[leveloffset=+1]
8+
9+
include::modules/service-accounts-default.adoc[leveloffset=+1]
10+
11+
include::modules/service-accounts-creating.adoc[leveloffset=+1]
12+
13+
include::modules/service-accounts-using-credentials-inside-a-container.adoc[leveloffset=+1]
14+
15+
include::modules/service-accounts-using-credentials-externally.adoc[leveloffset=+1]

‎modules/dedicated-admin-role-overview.adoc

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/using-service-accounts.adoc
4+
5+
[id='dedicated-admin-role-overview-{context}']
6+
ifdef::openshift-dedicated[]
7+
= About the dedicated administrator role
8+
9+
The accounts for dedicated administrators of an {product-title} cluster,
10+
have increased
11+
permissions and access to all user-created projects.
12+
13+
////
14+
[NOTE]
15+
====
16+
Some configuration changes or procedures discussed in this guide can be
17+
performed by only the {product-title} Operations Team. They are included in this
18+
guide for informational purposes to help you as an {product-title} cluster
19+
administrator better understand what configuration options are possible. If you
20+
want to request a change to your cluster that you cannot perform using the
21+
administrator CLI, open a support case on the
22+
https://access.redhat.com/support/[Red Hat Customer Portal].
23+
====
24+
////
25+
26+
When your account has the `dedicated-cluster-admin` authorization role
27+
bound to it, you
28+
are automatically bound to the `dedicated-project-admin` role for any new projects
29+
that users in the cluster create.
30+
31+
You can perform actions that are associated with a set of verbs, such as `create`,
32+
to operate on a set of resource names, such as `templates`. To view the details
33+
of these roles and their sets of
34+
verbs and resources, run the following commands:
35+
36+
----
37+
$ oc describe clusterrole/dedicated-cluster-admin
38+
$ oc describe clusterrole/dedicated-project-admin
39+
----
40+
41+
The verb names do not necessarily all map directly to `oc` commands but rather
42+
equate more generally to the types of CLI operations you can perform. For
43+
example, having the `list` verb means that you can display a list of all objects
44+
of a given resource name by running the `oc get` command, but the `get` verb
45+
means that you can display the details of a specific object if you know its name
46+
by runnign the `oc describe` command.
47+
48+
{product-title} administrators can grant users a `dedicated-reader` role, which
49+
provides view-only access at the cluster level and view access for all
50+
user projects.
51+
52+
endif::[]

‎modules/pod-using-a-different-service-account.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *
4+
5+
[id='pod-using-a-different-service-account-{context}']
6+
= Running a pod with a different service account
7+
8+
You can run a pod with a service account other than the default:
9+
10+
.Prerequisites
11+
12+
* Install the `oc` command line interface.
13+
* Configure a service account.
14+
* Create a deployment configuration.
15+
16+
.Procedure
17+
18+
. Edit the deployment configuration:
19+
+
20+
----
21+
$ oc edit dc/<deployment_config>
22+
----
23+
24+
. Add the `serviceAccount` and `serviceAccountName` parameters to the `spec`
25+
field, and specify the service account that you want to use:
26+
+
27+
----
28+
spec:
29+
securityContext: {}
30+
serviceAccount: <service_account>
31+
serviceAccountName: <service_account>
32+
----

‎modules/service-accounts-adding-secrets.adoc

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/using-service-accounts.adoc
4+
5+
[id='service-accounts-managing-secrets-{context}']
6+
== Managing secrets on a service account's pod
7+
8+
In addition to providing API credentials, a pod's service account determines
9+
which secrets the pod is allowed to use.
10+
11+
Pods use secrets in two ways:
12+
13+
* image pull secrets, providing credentials used to pull images for the pod's containers
14+
* mountable secrets, injecting the contents of secrets into containers as files
15+
16+
To allow a secret to be used as an image pull secret by a service account's
17+
pods, run:
18+
19+
----
20+
$ oc secrets link --for=pull <serviceaccount-name> <secret-name>
21+
----
22+
23+
To allow a secret to be mounted by a service account's pods, run:
24+
25+
----
26+
$ oc secrets link --for=mount <serviceaccount-name> <secret-name>
27+
----
28+
29+
[NOTE]
30+
====
31+
Limiting secrets to only the service accounts that reference them is disabled by
32+
default. This means that if `serviceAccountConfig.limitSecretReferences` is set
33+
to `false` (the default setting) in the master configuration file, mounting
34+
secrets to a service account's pods with the `--for=mount` option is not
35+
required. However, using the `--for=pull` option to enable using an image pull
36+
secret is required, regardless of the
37+
`serviceAccountConfig.limitSecretReferences` value.
38+
====
39+
40+
This example creates and adds secrets to a service account:
41+
42+
----
43+
$ oc create secret generic secret-plans \
44+
--from-file=plan1.txt \
45+
--from-file=plan2.txt
46+
secret/secret-plans
47+
48+
$ oc create secret docker-registry my-pull-secret \
49+
--docker-username=mastermind \
50+
--docker-password=12345 \
51+
--docker-email=mastermind@example.com
52+
secret/my-pull-secret
53+
54+
$ oc secrets link robot secret-plans --for=mount
55+
56+
$ oc secrets link robot my-pull-secret --for=pull
57+
58+
$ oc describe serviceaccount robot
59+
Name: robot
60+
Labels: <none>
61+
Image pull secrets: robot-dockercfg-624cx
62+
my-pull-secret
63+
64+
Mountable secrets: robot-token-uzkbh
65+
robot-dockercfg-624cx
66+
secret-plans
67+
68+
Tokens: robot-token-8bhpp
69+
robot-token-uzkbh
70+
----

‎modules/service-accounts-configuration-parameters.adoc

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/using-service-accounts.adoc
4+
5+
[id='service-accounts-configuration-parameters-{context}']
6+
= Service account configuration parameters
7+
8+
You can provide values for the following service account parameters in the
9+
*_/etc/origin/master/master-config.yml_* file on the master host.
10+
11+
.Service account configuration parameters
12+
[cols="3a,3a,6a",options="header"]
13+
|===
14+
15+
| Parameter Name | Type | Description
16+
17+
|`LimitSecretReferences`
18+
|Boolean
19+
|Controls whether or not to allow a service account to reference any secret in a
20+
namespace without explicitly referencing them.
21+
22+
|`ManagedNames`
23+
|String
24+
|A list of service account names that is automatically created in each namespace.
25+
If no names are specified, the `ServiceAccountsController` service does not
26+
start.
27+
28+
|`MasterCA`
29+
|String
30+
|The CA that verifies the TLS connection back to the master. The service account
31+
controller automatically injects the contents of this file into pods so they
32+
can verify connections to the master.
33+
34+
|`PrivateKeyFile`
35+
|String
36+
|A file that contains a PEM-encoded private RSA key, which is used to sign
37+
service account tokens. If no private key is specified, the service account
38+
`TokensController` service does not start.
39+
40+
|`PublicKeyFiles`
41+
|String
42+
|A list of files, each of which contains a PEM-encoded public RSA key. If any file
43+
contains a private key, the public portion of the key is used. The list of
44+
public keys is used to verify presented service account tokens. Each key is
45+
tried in order until the list is exhausted or verification succeeds. If no keys
46+
are specified, no service account authentication is available.
47+
48+
|`ServiceAccountConfig`
49+
|List
50+
|The parameter that contains the other listed service account parameters.
51+
52+
|===

‎modules/service-accounts-creating.adoc

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/using-service-accounts.adoc
4+
5+
[id='service-accounts-managing-{context}']
6+
= Creating service accounts
7+
8+
You can create a service account in a project and grant it permissions by
9+
binding it to a role.
10+
11+
.Procedure
12+
13+
. (Optional) To view the service accounts in the current project:
14+
+
15+
[source,bash]
16+
----
17+
$ oc get sa
18+
19+
NAME SECRETS AGE
20+
builder 2 2d
21+
default 2 2d
22+
deployer 2 2d
23+
----
24+
25+
. To create a new service account in the current project:
26+
+
27+
[source,bash]
28+
----
29+
$ oc create sa <service_account_name> <1>
30+
31+
serviceaccount "robot" created
32+
----
33+
<1> To create a service account in a different project, specify `-n <project_name>`.
34+
35+
. (Optional) View the secrets for the service account:
36+
+
37+
[source,bash]
38+
----
39+
$ oc describe sa robot
40+
Name: robot
41+
Namespace: project1
42+
Labels: <none>
43+
Annotations: <none>
44+
45+
Image pull secrets: robot-dockercfg-qzbhb
46+
47+
Mountable secrets: robot-token-f4khf
48+
robot-dockercfg-qzbhb
49+
50+
Tokens: robot-token-f4khf
51+
robot-token-z8h44
52+
----

‎modules/service-accounts-dedicated-admin-role.adoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/using-service-accounts.adoc
4+
5+
6+
[id='service-accounts-dedicated-admin-role-{context}']
7+
ifdef::openshift-dedicated[]
8+
= Service accounts in {product-title}
9+
10+
As an {product-title} administrator, you can use service accounts to perform any
11+
actions that require {product-title} `admin` roles.
12+
13+
The `dedicated-admin` service creates the `dedicated-admins` group. This group
14+
is granted the roles at the cluster or individual project
15+
level. Users can be assigned to this group, and group membership defines who has
16+
{product-title} administrator access. However, by design, service accounts
17+
cannot be added to regular groups.
18+
19+
Instead, the `dedicated-admin` service creates a special project for this
20+
purpose named `dedicated-admin`. The service account group for this project is
21+
granted {product-title} `admin` roles, which grants {product-title} administrator
22+
access to all service accounts within the `dedicated-admin` project. You can
23+
then use these service accounts to perform any actions that require
24+
{product-title} administrator access.
25+
26+
Users that are members of the `dedicated-admins` group are granted the
27+
`dedicated-admin` role permissions and have `edit` access to the `dedicated-admin`
28+
project. These users can manage the service accounts in this project
29+
and create new ones as needed.
30+
31+
Users with a `dedicated-reader` role are granted edit and view access to the
32+
`dedicated-reader` project and view-only access to the other projects.
33+
endif::[]

0 commit comments

Comments
 (0)