Add CR/CRD topics to 4.0

Rename administration/ -> masters/
Move catalog/* -> applications_and_projects/

_topic_map.yml

@@ -29,6 +29,13 @@ Topics:
 - Name: Welcome
   File: index
 ---
+Name: Applications and projects
+Dir: applications_and_projects
+Distros: openshift-*
+Topics:
+- Name: Managing resources from CRDs
+  File: crd-managing-resources-from-crds
+---
 Name: Builds
 Dir: builds
 Distros: openshift-*
@@ -158,14 +165,16 @@ Topics:
   File: creating-project-other-user
   Distros: openshift-enterprise,openshift-origin
 ---
-Name: Administration
-Dir: administration
+Name: Masters
+Dir: masters
 Distros: openshift-origin, openshift-enterprise
 Topics:
 - Name: Setting resource quotas per project
   File: quotas-setting-per-project
 - Name: Setting resource quotas across multiple projects
   File: quotas-setting-across-multiple-projects
+- Name: Extending the Kubernetes API with CRDs
+  File: crd-extending-api-with-crds
 ---
 Name: Networking
 Dir: networking

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

@@ -0,0 +1,10 @@
+[id='crd-managing-resources-from-crds']
+= Managing resources from Custom Resource Definitions
+include::modules/common-attributes.adoc[]
+:context: crd-managing-resources-from-crds
+
+toc::[]
+
+include::modules/crd-custom-resource-definitions.adoc[leveloffset=+1]
+include::modules/crd-creating-custom-resources-from-file.adoc[leveloffset=+1]
+include::modules/crd-inspecting-custom-resources.adoc[leveloffset=+1]

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

@@ -0,0 +1,12 @@
+[id='crd-extending-api-with-crds']
+= Extending the Kubernetes API with Custom Resource Definitions
+include::modules/common-attributes.adoc[]
+:context: crd-extending-api-with-crds
+
+toc::[]
+
+include::modules/crd-custom-resource-definitions.adoc[leveloffset=+1]
+include::modules/crd-creating-crds.adoc[leveloffset=+1]
+include::modules/crd-creating-aggregated-cluster-roles.adoc[leveloffset=+1]
+include::modules/crd-creating-custom-resources-from-file.adoc[leveloffset=+1]
+include::modules/crd-inspecting-custom-resources.adoc[leveloffset=+1]

masters/images

@@ -0,0 +1 @@
+../images/

masters/modules

@@ -0,0 +1 @@
+../modules/

masters/quotas-setting-across-multiple-projects.adoc

@@ -1,13 +1,6 @@
 [id='setting-quotas-across-multiple-projects']
 = Setting resource quotas across multiple projects
-{product-author}
-{product-version}
-:data-uri:
-:icons:
-:experimental:
-:toc: macro
-:toc-title:
-:prewrap!:
+include::modules/common-attributes.adoc[]
 :context: setting-quotas-across-multiple-projects
 
 toc::[]

masters/quotas-setting-per-project.adoc

@@ -1,13 +1,6 @@
 [id='quotas-setting-per-project']
 = Setting resource quotas per project
-{product-author}
-{product-version}
-:data-uri:
-:icons:
-:experimental:
-:toc: macro
-:toc-title:
-:prewrap!:
+include::modules/common-attributes.adoc[]
 :context: quotas-setting-per-project
 
 toc::[]

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

@@ -0,0 +1,79 @@
+// Module included in the following assemblies:
+//
+// * masters/extending-api-with-crds.adoc
+
+[id='crd-creating-aggregated-cluster-role-{context}']
+= Creating cluster roles for Custom Resource Definitions
+
+After creating a cluster-scoped Custom Resource Definition (CRD), cluster
+administrators can grant permissions to it. If you use the `admin`, `edit`, and
+`view` default cluster roles, take advantage of cluster role aggregation for
+their rules.
+
+[IMPORTANT]
+====
+You must explicitly assign permissions to each of these roles. The roles with
+more permissions do not inherit rules from roles with fewer permissions. If you
+assign a rule to a role, you must also assign that verb to roles that have more
+permissions. For example, if you grant the `get crontabs` permission to the view
+role, you must also grant it to the edit and admin roles. The admin or edit role
+is usually assigned to the user that created a project through the project
+template.
+====
+
+.Prerequisites
+
+- Create a CRD.
+
+.Procedure
+
+. Create a cluster role definition file for the CRD. The cluster role definition
+is a YAML file that contains the rules that apply to each cluster role. The
+{product-title} controller adds the rules that you specify to the default
+cluster roles.
++
+.Example YAML file for a cluster role definition
+[source,yaml]
+----
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1 <1>
+metadata:
+  name: name: aggregate-cron-tabs-admin-edit <2>
+  labels:
+    rbac.authorization.k8s.io/aggregate-to-admin: "true" <3>
+    rbac.authorization.k8s.io/aggregate-to-edit: "true" <4>
+rules:
+- apiGroups: ["stable.example.com"] <5>
+  resources: ["crontabs"] <6>
+  verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"] <7>
+---
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: aggregate-cron-tabs-view <2>
+  labels:
+    # Add these permissions to the "view" default role.
+    rbac.authorization.k8s.io/aggregate-to-view: "true" <8>
+    rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true" <9>
+rules:
+- apiGroups: ["stable.example.com"] <5>
+  resources: ["crontabs"] <6>
+  verbs: ["get", "list", "watch"] <7>
+----
+<1> Use the `apiextensions.k8s.io/v1beta1` API.
+<2> Specify a name for the definition.
+<3> Specify this label to grant permissions to the admin default role.
+<4> Specify this label to grant permissions to the edit default role.
+<5> Specify the group name of the CRD.
+<6> Specify the plural name of the CRD that these rules apply to.
+<7> Specify the verbs that represent the permissions that are granted to the role.
+For example, apply read and write permissions to the `admin` and `edit` roles
+and only read permission to the `view` role.
+<8> Specify this label to grant permissions to the `view` default role.
+<9> Specify this label to grant permissions to the `cluster-reader` default role.
+
+. Create the cluster role:
++
+----
+$ oc create -f <file_name>.yaml
+----

modules/crd-creating-crds.adoc

@@ -0,0 +1,74 @@
+// Module included in the following assemblies:
+//
+// * masters/extending-api-with-crds.adoc
+
+[id='crd-creating-custom-resources-definition-{context}']
+= Creating a Custom Resource Definition
+
+To create Custom Resource (CR) objects, cluster administrators must first create
+a Custom Resource Definition (CRD).
+
+.Prereqiusites
+
+- Access to an {product-title} cluster with `cluster-admin` user privileges.
+
+.Procedure
+
+To create a CRD:
+
+. Create a YAML file that contains the following field types:
++
+.Example YAML file for a CRD
+[source,yaml]
+----
+apiVersion: apiextensions.k8s.io/v1beta1 <1>
+kind: CustomResourceDefinition
+metadata:
+  name: crontabs.stable.example.com <2>
+spec:
+  group: stable.example.com <3>
+  version: v1 <4>
+  scope: Namespaced <5>
+  names:
+    plural: crontabs <6>
+    singular: crontab <7>
+    kind: CronTab <8>
+    shortNames:
+    - ct <9>
+----
+<1> Use the `apiextensions.k8s.io/v1beta1` API.
+<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.
+<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.
+<4> Specify a version name to be used in the URL. Each API Group can exist in multiple versions. For example: `v1alpha`, `v1beta`, `v1`.
+<5> Specify whether the custom objects are available to a project (`Namespaced`) or all projects
+in the cluster (`Cluster`).
+<6> Specify the plural name to use in the URL. The `plural` field is the same as a resource in an API URL.
+<7> Specify a singular name to use as an alias on the CLI and for display.
+<8> Specify the kind of objects that can be created. The type can be in CamelCase.
+<9> Specify a shorter string to match your resource on the CLI.
++
+[NOTE]
+====
+By default, a CRD is cluster-scoped and available to all projects.
+====
+
+. Create the CRD object:
++
+----
+$ oc create -f <file_name>.yaml
+----
++
+A new RESTful API endpoint is created at:
++
+----
+/apis/<spec:group>/<spec:version>/<scope>/*/<names-plural>/...
+----
++
+For example, using the example file, the following endpoint is created:
++
+----
+/apis/stable.example.com/v1/namespaces/*/crontabs/...
+----
++
+You can now use this endpoint URL to create and manage CRs. The object `Kind` is
+based on the `spec.kind` field of the CRD object you created.

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

@@ -0,0 +1,52 @@
+// Useful paired with modules/crd-inspecting-custom-resources.adoc
+//
+// Module included in the following assemblies:
+//
+// * applications_and_projects/crd-managing-resources-from-crds.adoc
+// * masters/extending-api-with-crds.adoc
+
+[id='crd-creating-custom-resources-from-file-{context}']
+= Creating Custom Resources from a file
+
+After a Custom Resource Definition (CRD) has been added to the cluster by a
+cluster administrator, Custom Resources (CRs) can be created with the CLI from a
+file using the CR specification.
+
+.Prerequisites
+
+- CRD added to the cluster by a cluster administrator.
+
+.Procedure
+
+. Create a YAML file for the CR. In the following example definition, the
+`cronSpec` and `image` custom fields are set in a CR of `Kind: CronTab`. The
+`Kind` comes from the `spec.kind` field of the CRD object.
++
+.Example YAML file for a CR
+[source,yaml]
+----
+apiVersion: "stable.example.com/v1" <1>
+kind: CronTab <2>
+metadata:
+  name: my-new-cron-object <3>
+  finalizers: <4>
+  - finalizer.stable.example.com
+spec: <5>
+  cronSpec: "* * * * /5"
+  image: my-awesome-cron-image
+----
++
+<1> Specify the group name and API version (name/version) from the custom resource definition.
+<2> Specify the type in the CRD.
+<3> Specify a name for the object.
+<4> Specify the
+link:https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#finalizers[finalizers]
+for the object, if any. Finalizers allow controllers to implement conditions
+that must be completed before the object can be deleted. <5> Specify conditions
+specific to the type of object.
+
+. After you create the file, create the object:
++
+----
+$ oc create -f <file_name>.yaml
+----

modules/crd-custom-resource-definitions.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * applications_and_projects/crd-managing-resources-from-crds.adoc
+// * masters/extending-api-with-crds.adoc
+
+[id='crd-custom-resource-definitions-{context}']
+= Custom Resource Definitions
+
+In the Kubernetes API, a resource is an endpoint that stores a collection of API
+objects of a certain kind. For example, the built-in Pods resource contains a
+collection of Pod objects.
+
+A _Custom Resource Definition_ (CRD) object defines a new, unique object `Kind`
+in the cluster and lets the Kubernetes API server handle its entire lifecycle.
+
+A _Custom Resource_ (CR) objects are created from CRDs that have been added to
+the cluster by a cluster administrator, allowing all cluster users to add the
+new resource type into projects.
+
+ifeval::["{context}" == "crd-extending-api-with-crds"]
+When a cluster administrator adds a new CRD to the cluster, the Kubernetes API
+server reacts by creating a new RESTful resource path that can be accessed by
+the entire cluster or a single project (namespace) and begins serving the
+specified CR.
+
+Cluster administrators that want to grant access to the CRD to other users can
+use cluster role aggregation to grant access to users with the `admin`, `edit`,
+or `view` default cluster roles. Cluster role aggregation allows the insertion
+of custom policy rules into these cluster roles. This behavior integrates the
+new resource into the cluster's RBAC policy as if it was a built-in resource.
+endif::[]
+
+Operators in particular make use of CRDs by packaging them with any required
+RBAC policy and other software-specific logic. Cluster administrators can also
+add CRDs manually to the cluster outside of an Operator's lifecycle, making them
+available to all users.
+
+[NOTE]
+====
+While only cluster administrators can create CRDs, developers can create the
+custom resource from an existing CRD if they have read and write permission to
+it.
+====

modules/crd-inspecting-custom-resources.adoc

@@ -0,0 +1,71 @@
+// Useful paired with modules/crd-creating-custom-resources-from-file.adoc
+//
+// Module included in the following assemblies:
+//
+// * applications_and_projects/crd-managing-resources-from-crds.adoc
+// * masters/extending-api-with-crds.adoc
+
+[id='crd-inspecting-custom-resources-{context}']
+= Inspecting Custom Resources
+
+After you create a Custom Resource (CR) object, you can inspect and get
+information about the created object using the CLI.
+
+.Prerequisites
+
+* Create a CR object.
+
+.Procedure
+
+. To get information on a specific `Kind` of a CR, run:
++
+----
+$ oc get <kind>
+----
++
+For example:
++
+----
+oc get crontab
+
+NAME                 KIND
+my-new-cron-object   CronTab.v1.stable.example.com
+----
++
+Resource names are not case-sensitive, and you can use either the singular or
+plural forms defined in the CRD, as well as any short name. For example:
++
+----
+oc get crontabs
+oc get crontab
+oc get ct
+----
+
+. You can also view the raw YAML data for a CR:
++
+----
+oc get <kind> -o yaml
+----
++
+----
+oc get ct -o yaml
+
+apiVersion: v1
+items:
+- apiVersion: stable.example.com/v1
+  kind: CronTab
+  metadata:
+    clusterName: ""
+    creationTimestamp: 2017-05-31T12:56:35Z
+    deletionGracePeriodSeconds: null
+    deletionTimestamp: null
+    name: my-new-cron-object
+    namespace: default
+    resourceVersion: "285"
+    selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object
+    uid: 9423255b-4600-11e7-af6a-28d2447dc82b
+  spec:
+    cronSpec: '* * * * /5' <1>
+    image: my-awesome-cron-image <1>
+----
+<1> Custom data from the YAML that you used to create the object displays.

modules/installing-docker.adoc

@@ -250,7 +250,7 @@ any associated physical volumes
 . Run `docker-storage-setup` again.
 
 See
-link:https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Logical_Volume_Manager_Administration/index.html[Logical Volume Manager Administration]
+link:https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Logical_Volume_Manager_masters/index.html[Logical Volume Manager Administration]
 for more detailed information about LVM management.
 
 .Enabling image signature support

modules/quotas-configuring-quota-sync-period.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quotas-configuring-quota-sync-period']
 [[]]

modules/quotas-creating-a-quota.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quotas-creating-a-quota']
 = Creating a quota
@@ -10,7 +10,7 @@ You can create a quota to constrain resource usage in a given project.
 .Procedure
 
 . Define the quota in a file. See
-xref:../administration/quotas-setting-per-project.adoc#quotas-sample-resource-quota-definitions[Sample resource quota definitions]
+xref:../masters/quotas-setting-per-project.adoc#quotas-sample-resource-quota-definitions[Sample resource quota definitions]
 for examples.
 
 . Use the file to create the quota and apply it to a project:

modules/quotas-creating-object-count-quotas.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quota-creating-object-count-quotas-{context}']
 == Creating object count quotas

modules/quotas-enforcement.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quota-enforcement-{context}']
 = Quota enforcement

modules/quotas-requests-vs-limits.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quotas-requests-vs-limits']
 = Requests versus limits

modules/quotas-requiring-explicit-quota.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quota-requiring-explicit-quota-{context}']
 == Requiring explicit quota to consume a resource

modules/quotas-resources-managed.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quotas-resources-managed-{context}']
 = Resources managed by quotas

modules/quotas-sample-resource-quotas-def.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quotas-sample-resource-quota-definitions']
 = Sample resource quota definitions

modules/quotas-scopes.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quotas-scopes-{context}']
 = Quota scopes

modules/quotas-selecting-projects.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-across-multiple-projects.adoc
+// * masters/quotas-setting-across-multiple-projects.adoc
 
 [id='quotas-setting-projects-{context}']
 = Selecting multiple projects during quota creation

modules/quotas-selection-granularity.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-across-multiple-projects.adoc
+// * masters/quotas-setting-across-multiple-projects.adoc
 
 [id='quotas-selection-granularity-{context}']
 = Selection granularity

modules/quotas-viewing-clusterresourcequotas.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-across-multiple-projects.adoc
+// * masters/quotas-setting-across-multiple-projects.adoc
 
 [id='quotas-viewing-clusterresourcequotas-{context}']
 = Viewing applicable ClusterResourceQuotas

modules/quotas-viewing-quotas.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/quotas-setting-per-project.adoc
+// * masters/quotas-setting-per-project.adoc
 
 [id='quota-viewing-quotas-{context}']
 = Viewing a quota

modules/setting-resource-quota-for-extended-resources.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * administration/setting-quotas-per-project.adoc
+// * masters/setting-quotas-per-project.adoc
 
 [id='setting-resource-quota-for-extended-resources-{context}']
 = Setting resource quota for extended resources