Skip to content

Commit 2dd70c0

Browse files
adellapeadellape
committed
Add CR/CRD topics to 4.0
Rename administration/ -> masters/ Move catalog/* -> applications_and_projects/
1 parent 390e2f8 commit 2dd70c0

27 files changed

+372
-34
lines changed

‎_topic_map.yml

+11-2
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,13 @@ Topics:
2929
- Name: Welcome
3030
File: index
3131
---
32+
Name: Applications and projects
33+
Dir: applications_and_projects
34+
Distros: openshift-*
35+
Topics:
36+
- Name: Managing resources from CRDs
37+
File: crd-managing-resources-from-crds
38+
---
3239
Name: Builds
3340
Dir: builds
3441
Distros: openshift-*
@@ -158,14 +165,16 @@ Topics:
158165
File: creating-project-other-user
159166
Distros: openshift-enterprise,openshift-origin
160167
---
161-
Name: Administration
162-
Dir: administration
168+
Name: Masters
169+
Dir: masters
163170
Distros: openshift-origin, openshift-enterprise
164171
Topics:
165172
- Name: Setting resource quotas per project
166173
File: quotas-setting-per-project
167174
- Name: Setting resource quotas across multiple projects
168175
File: quotas-setting-across-multiple-projects
176+
- Name: Extending the Kubernetes API with CRDs
177+
File: crd-extending-api-with-crds
169178
---
170179
Name: Networking
171180
Dir: networking

‎applications_and_projects/crd-managing-resources-from-crds.adoc

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[id='crd-managing-resources-from-crds']
2+
= Managing resources from Custom Resource Definitions
3+
include::modules/common-attributes.adoc[]
4+
:context: crd-managing-resources-from-crds
5+
6+
toc::[]
7+
8+
include::modules/crd-custom-resource-definitions.adoc[leveloffset=+1]
9+
include::modules/crd-creating-custom-resources-from-file.adoc[leveloffset=+1]
10+
include::modules/crd-inspecting-custom-resources.adoc[leveloffset=+1]

‎masters/crd-extending-api-with-crds.adoc

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[id='crd-extending-api-with-crds']
2+
= Extending the Kubernetes API with Custom Resource Definitions
3+
include::modules/common-attributes.adoc[]
4+
:context: crd-extending-api-with-crds
5+
6+
toc::[]
7+
8+
include::modules/crd-custom-resource-definitions.adoc[leveloffset=+1]
9+
include::modules/crd-creating-crds.adoc[leveloffset=+1]
10+
include::modules/crd-creating-aggregated-cluster-roles.adoc[leveloffset=+1]
11+
include::modules/crd-creating-custom-resources-from-file.adoc[leveloffset=+1]
12+
include::modules/crd-inspecting-custom-resources.adoc[leveloffset=+1]

‎masters/images

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../images/

‎masters/modules

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../modules/

‎administration/quotas-setting-across-multiple-projects.adoc renamed to ‎masters/quotas-setting-across-multiple-projects.adoc

+1-8
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,6 @@
11
[id='setting-quotas-across-multiple-projects']
22
= Setting resource quotas across multiple projects
3-
{product-author}
4-
{product-version}
5-
:data-uri:
6-
:icons:
7-
:experimental:
8-
:toc: macro
9-
:toc-title:
10-
:prewrap!:
3+
include::modules/common-attributes.adoc[]
114
:context: setting-quotas-across-multiple-projects
125

136
toc::[]

‎administration/quotas-setting-per-project.adoc renamed to ‎masters/quotas-setting-per-project.adoc

+1-8
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,6 @@
11
[id='quotas-setting-per-project']
22
= Setting resource quotas per project
3-
{product-author}
4-
{product-version}
5-
:data-uri:
6-
:icons:
7-
:experimental:
8-
:toc: macro
9-
:toc-title:
10-
:prewrap!:
3+
include::modules/common-attributes.adoc[]
114
:context: quotas-setting-per-project
125

136
toc::[]

‎modules/crd-creating-aggregated-cluster-roles.adoc

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * masters/extending-api-with-crds.adoc
4+
5+
[id='crd-creating-aggregated-cluster-role-{context}']
6+
= Creating cluster roles for Custom Resource Definitions
7+
8+
After creating a cluster-scoped Custom Resource Definition (CRD), cluster
9+
administrators can grant permissions to it. If you use the `admin`, `edit`, and
10+
`view` default cluster roles, take advantage of cluster role aggregation for
11+
their rules.
12+
13+
[IMPORTANT]
14+
====
15+
You must explicitly assign permissions to each of these roles. The roles with
16+
more permissions do not inherit rules from roles with fewer permissions. If you
17+
assign a rule to a role, you must also assign that verb to roles that have more
18+
permissions. For example, if you grant the `get crontabs` permission to the view
19+
role, you must also grant it to the edit and admin roles. The admin or edit role
20+
is usually assigned to the user that created a project through the project
21+
template.
22+
====
23+
24+
.Prerequisites
25+
26+
- Create a CRD.
27+
28+
.Procedure
29+
30+
. Create a cluster role definition file for the CRD. The cluster role definition
31+
is a YAML file that contains the rules that apply to each cluster role. The
32+
{product-title} controller adds the rules that you specify to the default
33+
cluster roles.
34+
+
35+
.Example YAML file for a cluster role definition
36+
[source,yaml]
37+
----
38+
kind: ClusterRole
39+
apiVersion: rbac.authorization.k8s.io/v1 <1>
40+
metadata:
41+
name: name: aggregate-cron-tabs-admin-edit <2>
42+
labels:
43+
rbac.authorization.k8s.io/aggregate-to-admin: "true" <3>
44+
rbac.authorization.k8s.io/aggregate-to-edit: "true" <4>
45+
rules:
46+
- apiGroups: ["stable.example.com"] <5>
47+
resources: ["crontabs"] <6>
48+
verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"] <7>
49+
---
50+
kind: ClusterRole
51+
apiVersion: rbac.authorization.k8s.io/v1
52+
metadata:
53+
name: aggregate-cron-tabs-view <2>
54+
labels:
55+
# Add these permissions to the "view" default role.
56+
rbac.authorization.k8s.io/aggregate-to-view: "true" <8>
57+
rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true" <9>
58+
rules:
59+
- apiGroups: ["stable.example.com"] <5>
60+
resources: ["crontabs"] <6>
61+
verbs: ["get", "list", "watch"] <7>
62+
----
63+
<1> Use the `apiextensions.k8s.io/v1beta1` API.
64+
<2> Specify a name for the definition.
65+
<3> Specify this label to grant permissions to the admin default role.
66+
<4> Specify this label to grant permissions to the edit default role.
67+
<5> Specify the group name of the CRD.
68+
<6> Specify the plural name of the CRD that these rules apply to.
69+
<7> Specify the verbs that represent the permissions that are granted to the role.
70+
For example, apply read and write permissions to the `admin` and `edit` roles
71+
and only read permission to the `view` role.
72+
<8> Specify this label to grant permissions to the `view` default role.
73+
<9> Specify this label to grant permissions to the `cluster-reader` default role.
74+
75+
. Create the cluster role:
76+
+
77+
----
78+
$ oc create -f <file_name>.yaml
79+
----

‎modules/crd-creating-crds.adoc

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * masters/extending-api-with-crds.adoc
4+
5+
[id='crd-creating-custom-resources-definition-{context}']
6+
= Creating a Custom Resource Definition
7+
8+
To create Custom Resource (CR) objects, cluster administrators must first create
9+
a Custom Resource Definition (CRD).
10+
11+
.Prereqiusites
12+
13+
- Access to an {product-title} cluster with `cluster-admin` user privileges.
14+
15+
.Procedure
16+
17+
To create a CRD:
18+
19+
. Create a YAML file that contains the following field types:
20+
+
21+
.Example YAML file for a CRD
22+
[source,yaml]
23+
----
24+
apiVersion: apiextensions.k8s.io/v1beta1 <1>
25+
kind: CustomResourceDefinition
26+
metadata:
27+
name: crontabs.stable.example.com <2>
28+
spec:
29+
group: stable.example.com <3>
30+
version: v1 <4>
31+
scope: Namespaced <5>
32+
names:
33+
plural: crontabs <6>
34+
singular: crontab <7>
35+
kind: CronTab <8>
36+
shortNames:
37+
- ct <9>
38+
----
39+
<1> Use the `apiextensions.k8s.io/v1beta1` API.
40+
<2> Specify a name for the definition. This must be in the <plural-name><group> format using the values from the `group` and `plural` fields.
41+
<3> Specify a group name for the API. An API group is a collection of objects that are logically related. For example, all batch objects like `Job` or `ScheduledJob` could be in the batch API Group (such as batch.api.example.com). A good practice is to use a fully-qualified-domain name of your organization.
42+
<4> Specify a version name to be used in the URL. Each API Group can exist in multiple versions. For example: `v1alpha`, `v1beta`, `v1`.
43+
<5> Specify whether the custom objects are available to a project (`Namespaced`) or all projects
44+
in the cluster (`Cluster`).
45+
<6> Specify the plural name to use in the URL. The `plural` field is the same as a resource in an API URL.
46+
<7> Specify a singular name to use as an alias on the CLI and for display.
47+
<8> Specify the kind of objects that can be created. The type can be in CamelCase.
48+
<9> Specify a shorter string to match your resource on the CLI.
49+
+
50+
[NOTE]
51+
====
52+
By default, a CRD is cluster-scoped and available to all projects.
53+
====
54+
55+
. Create the CRD object:
56+
+
57+
----
58+
$ oc create -f <file_name>.yaml
59+
----
60+
+
61+
A new RESTful API endpoint is created at:
62+
+
63+
----
64+
/apis/<spec:group>/<spec:version>/<scope>/*/<names-plural>/...
65+
----
66+
+
67+
For example, using the example file, the following endpoint is created:
68+
+
69+
----
70+
/apis/stable.example.com/v1/namespaces/*/crontabs/...
71+
----
72+
+
73+
You can now use this endpoint URL to create and manage CRs. The object `Kind` is
74+
based on the `spec.kind` field of the CRD object you created.

‎modules/crd-creating-custom-resources-from-file.adoc

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Useful paired with modules/crd-inspecting-custom-resources.adoc
2+
//
3+
// Module included in the following assemblies:
4+
//
5+
// * applications_and_projects/crd-managing-resources-from-crds.adoc
6+
// * masters/extending-api-with-crds.adoc
7+
8+
[id='crd-creating-custom-resources-from-file-{context}']
9+
= Creating Custom Resources from a file
10+
11+
After a Custom Resource Definition (CRD) has been added to the cluster by a
12+
cluster administrator, Custom Resources (CRs) can be created with the CLI from a
13+
file using the CR specification.
14+
15+
.Prerequisites
16+
17+
- CRD added to the cluster by a cluster administrator.
18+
19+
.Procedure
20+
21+
. Create a YAML file for the CR. In the following example definition, the
22+
`cronSpec` and `image` custom fields are set in a CR of `Kind: CronTab`. The
23+
`Kind` comes from the `spec.kind` field of the CRD object.
24+
+
25+
.Example YAML file for a CR
26+
[source,yaml]
27+
----
28+
apiVersion: "stable.example.com/v1" <1>
29+
kind: CronTab <2>
30+
metadata:
31+
name: my-new-cron-object <3>
32+
finalizers: <4>
33+
- finalizer.stable.example.com
34+
spec: <5>
35+
cronSpec: "* * * * /5"
36+
image: my-awesome-cron-image
37+
----
38+
+
39+
<1> Specify the group name and API version (name/version) from the custom resource definition.
40+
<2> Specify the type in the CRD.
41+
<3> Specify a name for the object.
42+
<4> Specify the
43+
link:https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#finalizers[finalizers]
44+
for the object, if any. Finalizers allow controllers to implement conditions
45+
that must be completed before the object can be deleted. <5> Specify conditions
46+
specific to the type of object.
47+
48+
. After you create the file, create the object:
49+
+
50+
----
51+
$ oc create -f <file_name>.yaml
52+
----

‎modules/crd-custom-resource-definitions.adoc

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * applications_and_projects/crd-managing-resources-from-crds.adoc
4+
// * masters/extending-api-with-crds.adoc
5+
6+
[id='crd-custom-resource-definitions-{context}']
7+
= Custom Resource Definitions
8+
9+
In the Kubernetes API, a resource is an endpoint that stores a collection of API
10+
objects of a certain kind. For example, the built-in Pods resource contains a
11+
collection of Pod objects.
12+
13+
A _Custom Resource Definition_ (CRD) object defines a new, unique object `Kind`
14+
in the cluster and lets the Kubernetes API server handle its entire lifecycle.
15+
16+
A _Custom Resource_ (CR) objects are created from CRDs that have been added to
17+
the cluster by a cluster administrator, allowing all cluster users to add the
18+
new resource type into projects.
19+
20+
ifeval::["{context}" == "crd-extending-api-with-crds"]
21+
When a cluster administrator adds a new CRD to the cluster, the Kubernetes API
22+
server reacts by creating a new RESTful resource path that can be accessed by
23+
the entire cluster or a single project (namespace) and begins serving the
24+
specified CR.
25+
26+
Cluster administrators that want to grant access to the CRD to other users can
27+
use cluster role aggregation to grant access to users with the `admin`, `edit`,
28+
or `view` default cluster roles. Cluster role aggregation allows the insertion
29+
of custom policy rules into these cluster roles. This behavior integrates the
30+
new resource into the cluster's RBAC policy as if it was a built-in resource.
31+
endif::[]
32+
33+
Operators in particular make use of CRDs by packaging them with any required
34+
RBAC policy and other software-specific logic. Cluster administrators can also
35+
add CRDs manually to the cluster outside of an Operator's lifecycle, making them
36+
available to all users.
37+
38+
[NOTE]
39+
====
40+
While only cluster administrators can create CRDs, developers can create the
41+
custom resource from an existing CRD if they have read and write permission to
42+
it.
43+
====

0 commit comments

Comments
 (0)