Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time

Documentation guidelines

General file guidelines

  • Set your editor to strip trailing whitespace.

  • Do not hard wrap lines at 80 characters (or at any other length).

    It is not necessary to update existing content to unwrap lines, but you can remove existing hard wrapping from any lines that you are currently working in.

    Tip

    In the Atom editor, you can use Ctrl+J to undo hard wrapping on a paragraph.

Assembly file metadata

Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:

[id="<unique-heading-for-assembly>"]                            (1)
= Assembly title                                                (2)
include::modules/common-attributes.adoc[]                       (3)
:context: <unique-context-for-assembly>                         (4)
                                                                (5)
toc::[]                                                         (6)
  1. A unique (within OpenShift docs) anchor id for this assembly. Example: cli-developer-commands

  2. Human readable title (notice the '=' top-level header)

  3. Includes attributes common to OpenShift docs.

    Note

    The {product-name} and {product-version} common attributes are not defined in the modules/common-attributes.adoc file. Those attributes are pulled by AsciiBinder from the distro mapping definitions in the _distro_map.yml file. See Product name and version for more information on this topic.

  4. Context used for identifying headers in modules that is the same as the anchor id. Example: cli-developer-commands.

  5. A blank line. You must have a blank line here before the toc.

  6. The table of contents for the current assembly.

After the heading block and a single whitespace line, you can include any content for this assembly.

Note

The assembly title, which is the first line of the document, is the only level 1 ( = ) title. Section headers within the assembly must be level 2 ( == ) or lower. When you include modules, you must add leveloffsets in the include statements. You can manually add more level 2 or lower section headers in the assembly.

Module file metadata

Every module should be placed in the modules folder and should contain the following metadata at the top:

// Module included in the following assemblies:
//
// * list of assemblies where this module is included              (1)

[id="<module-anchor>_{context}"]                                   (2)
= Module title                                                     (3)
  1. List of assemblies in which this module is included.

  2. A module anchor with {context} that must match the module’s file name.

  3. Human readable title. To ensure consistency in the results of the leveloffset values in include statements, you must use a level one heading ( = ) for the module title.

Example:

// Module included in the following assemblies:
//
// * cli_reference/openshift_cli/developer-cli-commands.adoc

[id="cli-basic-commands_{context}"]
= Basic CLI commands

Text snippet file metadata

Every text snippet should be placed in the snippets folder and should contain the following metadata at the top:

// Text snippet included in the following assemblies: (1)
//
// * list of assemblies where this text snippet is included
//
// Text snippet included in the following modules:    (2)
//
// * list of modules where this text snippet is included
  1. List of assemblies in which this text snippet is included.

  2. List of modules in which this text snippet is included.

Note

An anchor ID and human readable title are not required metadata. This type of component is text only and not intended to be published or cross referenced on its own. See Writing text snippets.

Example:

// Text snippet included in the following assemblies:
//
// * installing/installing_aws/installing-aws-default.adoc
// * installing/installing_azure/installing-azure-default.adoc
// * installing/installing_gcp/installing-gcp-default.adoc

In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.

Assembly/module file names

Try to shorten the file name as much as possible without abbreviating important terms that may cause confusion. For example, the managing-authorization-policies.adoc file name would be appropriate for an assembly titled "Managing Authorization Policies".

Directory names

If you create a directory with a multiple-word name, separate each word with an underscore, for example backup_and_restore. Do not create a top-level directory in the repository without checking with the docs team. In the main OpenShift docs, you can create one level of subdirectories. In the docs for features that are designed to be used with OpenShift, such as Service Mesh and OpenShift virtualization, you can create two levels of subdirectories.

When creating a new directory or subdirectory, you must create two symbolic links in it:

  • An images symbolic link to the top-level images/ directory

  • A modules symbolic link to the top-level modules/ directory

  • If you are including a text snippet in your modules or assemblies, a snippets symbolic link to the top-level snippets/ directory

If the directory that contains an assembly does not have the images symbolic link, any images in that assembly or its modules will not be included properly when building the docs.

Tip

To create the symbolic links:

  1. Navigate to the directory that you need to add the links in.

  2. Use the following command to create a symbolic link:

    $ ln -s <target_directory> <link_name>

    For example, if you are creating the links in a directory that is two levels deep, such as cli_reference/openshift_cli, use the following commands:

    $ ln -s ../../images/ images
    $ ln -s ../../modules/ modules

    Be sure to adjust the number of levels to back up (../) depending on how deep your directory is.

If you accidentally create an incorrect link, you can remove that link by using unlink <link_name>.

Assembly/Module titles and section headings

Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.

Try to be as descriptive as possible with the title or section headings without making them unnecessarily long. For assemblies and task modules, use a gerund form in headings, such as:

  • Creating

  • Managing

  • Using

Do not use "Overview" as a heading.

Do not use backticks or other markup in assembly or module headings.

Discrete headings

If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:

A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a == section level to a ==== level if you wanted for some style reason).

To use a discrete heading, just add [discrete] to the line before your unique ID. For example:

[discrete]
[id="managing-authorization-policies_{context}"]
== Managing authorization policies

Anchoring titles and section headings

All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading.

Anchoring in assembly files

The following is an example anchor ID in an assembly file:

[id="configuring-alert-notifications"]
= Configuring alert notifications
Note

Do not include line spaces between the anchor ID and the section title.

Anchoring in module files

You must add the {context} variable to the end of anchor IDs in module files. When called, the {context} variable is resolved into the value declared in the :context: attribute in the corresponding assembly file. This enables cross-referencing to module IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.

The following is an example of an anchor ID in a module file:

[id="sending-notifications-to-external-systems_{context}"]
= Sending notifications to external systems
Note

The {context} variable must be preceded by an underscore (_) when declared in an anchor ID.

Anchoring "Prerequisites", "Additional resources", and "Next steps" titles in assemblies

Use unique IDs for "Prerequisites", "Additional resources", and "Next steps" titles in assemblies. You can add the prefixes prerequisites_, additional-resources_, or next-steps_ to a unique string that describes the assembly topic. The unique string can match the value assigned to the :context: attribute in the assembly.

Note

The prerequisites_, additional-resources_, and next-steps_ prefixes must end with an underscore (_) when declared in an anchor ID in an assembly.

The following examples include IDs that are unique to the "Configuring alert notifications" assembly:

Example unique ID for a "Prerequisites" title

[id="prerequisites_configuring-alert-notifications"]
== Prerequisites

Example unique ID for an "Additional resources" title

[id="additional-resources_configuring-alert-notifications"]
== Additional resources

Example unique ID for a "Next steps" title

[id="next-steps_configuring-alert-notifications"]
== Next steps

Writing assemblies

An assembly is a collection of modules that describes how to accomplish a user story.

For more information about forming assemblies, see the Red Hat modular docs reference guide and the assembly template.

Note

When using the "Prerequisites", "Next steps", or "Additional resources" headings in an assembly, use == formatting, such as == Prerequisites or == Additional resources. Use of this heading syntax at the assembly level indicates that the sections relate to the whole assembly.

Only use . formatting (.Additional resources) to follow a module in an assembly. Because you cannot use the xrefs in modules, this functions as a trailing include at the assembly level, where the . formatting of the include statement indicates that the resource applies specifically to the module and not to the assembly.

Writing concepts

A concept contains information to support the tasks that users want to do and must not include task information like commands or numbered steps. In most cases, create your concepts as individual modules and include them in appropriate assemblies.

Avoid using gerunds in concept titles. "About <concept>" is a common concept module title.

For more information about creating concept modules, see the Red Hat modular docs reference guide and the concept template.

Writing procedures

A procedure contains the steps that users follow to complete a process or task. Procedures contain ordered steps and explicit commands. In most cases, create your procedures as individual modules and include them in appropriate assemblies.

Use a gerund in the procedure title, such as "Creating".

For more information about writing procedures, see the Red Hat modular docs reference guide and the procedure template.

Note

When needed, use .Prerequisites, .Next steps, or .Additional resources syntax to suppress TOC formatting within a module. Do not use == syntax for these headings in modules. Because you cannot use the xrefs in modules, if you need to include a link under one of these headings, place the entire subsection in the assembly instead.

Writing text snippets

A text snippet is an optional component that lets you reuse content in multiple modules and assemblies. Text snippets are not a substitute for modules, but instead are a more granular form of content reuse. While a module is content that a reader can understand on its own (like an article) or as part of a larger body of work (like an assembly), a text snippet is not self-contained and is not intended to be published or cross referenced on its own.

In the context of modules and assemblies, text snippets do not include headings or anchor IDs. This type of component is text only. Examples include the following:

  • Admonitions that appear in multiple modules.

  • An introductory paragraph that appears in multiple assemblies.

  • The same series of steps that appear in multiple procedure modules.

  • A deprecation statement that appears in multiple sets of release notes.

Example:

You could write the the following paragraph once and include it in each assembly that explains how to install a cluster using the installer-provisioned default values:

In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.
Note

In the example, cloud-provider-first and cloud-provider are not defined by the common-attributes module. If you use an attribute that is not common to OpenShift docs, make sure to define it locally in either the assembly or module, depending on where the text snippet is included.

For more information about creating text snippets, see the Red Hat modular docs reference guide

Using conscious language

To assist with the removal of the problematic word "master" from the documentation, use the following terminology when referring to OpenShift control plane nodes:

Branch Control plane node reference

main and enterprise-4.9

Control plane node

enterprise-4.8 and earlier

Control plane (also known as master) node

enterprise-3.11

Master node

You can replace "node" in the preceding examples with "machine", "host", or another suitable description.

Note

If you are cherry picking from main to enterprise-4.8 or earlier, you must manually cherry pick to include the “(also known as master)” phrasing. This is required only if the phrase “control plane” is introduced for the first time in an assembly or module.

Adding a subsection on making open source more inclusive

If you create a release notes assembly for a sub-product within the openshift/openshift-docs repo, you might include a "Making open source more inclusive" statement. Instead of pasting the statement from the OpenShift Release Notes, use the following module, which is available in the enterprise-4.8 branch and later:

include::modules/making-open-source-more-inclusive.adoc[leveloffset=+1]

Product name and version

When possible, generalize references to the product name and/or version by using the {product-title} and/or {product-version} attributes. These attributes are pulled by AsciiBinder from the distro mapping definitions in the _distro_map.yml file.

The {product-title} comes from the first name: field in a distro mapping, while the associated {product-version} comes from the name: fields on any branches: defined.

How these attributes render is dependent on which distro and branch build you are viewing. The following table shows the current distros and the possible values for {product-title} and {product-version}.

Distro {product-title} {product-version}

openshift-origin

OKD

1.2, 1.3, 1.4, 1.5, 3.6, 3.7, 3.9, 3.10, 3.11, Latest

openshift-enterprise

OpenShift Container Platform

3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.9, 3.10, 3.11, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7

openshift-dedicated

OpenShift Dedicated

Latest

openshift-online

OpenShift Online

Latest

For example:

You can deploy applications on {product-title}.

This is a safe statement that could appear in probably any of the builds, so an ifdef/endif statement is not necessary. For example, if you were viewing a build for the openshift-enterprise distro (for any of the distro-defined branches), this would render as:

You can deploy applications on OpenShift Container Platform.

And for the openshift-origin distro:

You can deploy applications on OKD.

Considering that we use distinct branches to keep content for product versions separated, global use of {product-version} across all branches is probably less useful, but it is available if you come across a requirement for it. Just consider how it will render across any branches that the content appears in.

If it makes more sense in context to refer to the major version of the product instead of a specific minor version (for example, if comparing how something in OpenShift Container Platform 4 differs from OpenShift Container Platform 3), just use the major version number. Do not prepend with a v, as in v3 or v4.

Note

Other common attribute values are defined in the modules/common-attributes.adoc file. Where possible, generalize references to those values by using the common attributes. For example, use {cloud-redhat-com} to refer to Red Hat OpenShift Cluster Manager.

Node names

Do not use internal company server names in commands or example output. Provide generic OpenShift Container Platform node name examples that are not provider-specific, unless required. Where possible, use the example.com domain name when providing fully qualified domain names (FQDNs).

The following table includes example OpenShift Container Platform 4 node names and their corresponding role types:

Node name Role type

node-1.example.com

You can use this format for nodes that do not need role-specific node names.

node-2.example.com

node-3.example.com

control-plane-1.example.com

You can use this format if you need to describe the control plane role type within a node name.

control-plane-2.example.com

control-plane-3.example.com

compute-1.example.com

You can use this format if you need to describe the compute node role type within a node name.

compute-2.example.com

bootstrap.example.com

You can use this format if you need to describe the bootstrap node role type within a node name.

This example lists the status of cluster nodes that use the node name formatting guidelines:

[source,terminal]
----
$ oc get nodes
----
+
.Example output
[source,terminal]
----
NAME                          STATUS   ROLES    AGE   VERSION
compute-1.example.com         Ready    worker   33m   v1.19.0+9f84db3
control-plane-1.example.com   Ready    master   41m   v1.19.0+9f84db3
control-plane-2.example.com   Ready    master   45m   v1.19.0+9f84db3
compute-2.example.com         Ready    worker   38m   v1.19.0+9f84db3
compute-3.example.com         Ready    worker   33m   v1.19.0+9f84db3
control-plane-3.example.com   Ready    master   41m   v1.19.0+9f84db3
----
Note

Some provider-formatted hostnames include IPv4 addresses. An OpenShift Container Platform node name typically reflects the hostname of a node. If node names in your output need to be provider-specific and require this format, use private IPv4 addresses. For example, you could use ip-10-0-48-9.example.com as a node name that includes a private IPv4 address.

IP addresses

You may include IPv4 addresses from test clusters in examples in the documentation, as long as they are private. Private IPv4 addresses fall into one of the following ranges:

  • 10.0.0.0 to 10.255.255.255 (class A address block 10.0.0.0/8)

  • 172.16.0.0 to 172.31.255.255 (class B address block 172.16.0.0/12)

  • 192.168.0.0 to 192.168.255.255 (class C address block 192.168.0.0/16)

Replace all public IP addresses with an address from the following blocks. These address blocks are reserved for documentation:

  • 192.0.2.0 to 192.0.2.255 (TEST-NET-1 address block 192.0.2.0/24)

  • 198.51.100.0 to 198.51.100.255 (TEST-NET-2 address block 198.51.100.0/24)

  • 203.0.113.0 to 203.0.113.255 (TEST-NET-3 address block 203.0.113.0/24)

Note

There might be advanced networking examples that require specific IP addresses, or cloud provider-specific examples that require a public IP address. Contact a subject matter expert if you need assistance with replacing IP addresses.

Links can be used to cross-reference internal assemblies or send readers to external information resources for further reading.

In OpenShift docs:

  • All links to internal content is created using xref and must have an anchor ID.

  • Only use xref in assemblies, not modules.

  • All links to external websites are created using link.

Important

Do not split link paths across lines when wrapping text. This will cause issues with the doc builds.

Example URLs

To provide an example URL path that you do not want to render as a hyperlink, use this format:

`\https://www.example.com`

Internal cross-references

Whenever possible the link to another assembly should be part of the actual sentence. Avoid creating links as a separate sentence that begins with "See [this assembly] for more information on x".

Note

Use the relative file path (from the file you are editing, to the file you are linking to), even if you are linking to the same directory that you are writing in. This makes search and replace operations to fix broken links much easier.

For example, if you are writing in architecture/core_concepts/deployments.adoc and you want to link to architecture/core_concepts/routes.adoc then you must include the path back to the first level of the assembly directory:

xref:../../architecture/networking/routes.adoc#architecture-core-concepts-routes
Markup example of cross-referencing
Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or
the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI].

Before you can create a domain, you must first xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[create an application].
Rendered output of cross-referencing

Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the OpenShift CLI.

Before you can create a domain, you must first create an application.

If you want to link to a different website, use:

link:http://othersite.com/otherpath[friendly reference text]
Important
You must use link: before the start of the URL.
Important
You cannot link to a repository that is hosted on www.github.com.
Tip
If you want to build a link from a URL without changing the text from the actual URL, just print the URL without adding a [friendly text] block at the end; it will automatically be rendered as a link.

There are two scenarios for linking to other assemblies:

  1. Link to another file that exists in the same directory.

  2. Link to another file that exists in a separate directory.

The following examples use the example directory structure shown here:

/
/foo
/foo/bar.adoc
/baz
/baz/zig.adoc
/baz/zag.adoc

Link to assembly in same directory

xref:<filename>#anchor-id[friendly title]

You must use the .adoc file extension. The document processor will correctly link this to the resulting HTML file.

For example, using the above syntax, if you are working on zig.adoc and want to link to zag.adoc, do it this way:

xref:../zag.adoc#baz-zag[comment]

where baz-zag is the anchor ID at the top of the file zag.adoc.

Link to assembly in different directory

xref:../dir/<filename>.adoc#anchor-id[friendly title]

For example, if you are working on bar.adoc and you want to link to zig.adoc, do it this way:

xref:../baz/zig.adoc#baz-zig[see the ZIG manual for more]
Note

You must use the .adoc extension in order for the link to work correctly and you must specify an anchor ID.

Embedding an external file

You can embed content hosted outside the openshift-docs GitHub repository by using the include directive to target the URI of a raw file. This is helpful for cases where content frequently changes; you embed the raw file and the content auto-updates based on the changes made to the content on its host site.

Important

You are restricted to only embed files from GitHub repositories managed by the openshift GitHub user. You must also prefix your external file URI with https. URIs beginning with http are forbidden for security reasons and will fail the documentation build.

For example, if you want to embed the 01_vnet.json template, include the URI of its raw file version like this:

.`01_vnet.json` ARM template
[source,json]
----
include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/01_vnet.json[]
----
Note

Embedding external files is restricted for files that change frequently, like templates. You must ensure that embedded files are QE verified before they are updated on their host site.

Note

You must get approval from the Engineering, QE, and Docs teams before embedding an external file.

Indicating Technology Preview features

To indicate that a feature is in Technology Preview, include the modules/technology-preview.adoc file in the feature’s assembly to keep the supportability wording consistent across Technology Preview features and provide a value for the :FeatureName: variable before you include this module.

See an example of how this is applied.

Indicating deprecated features

To indicate that a feature is deprecated, include the modules/deprecated-feature.adoc file in the feature’s assembly, or to each relevant assembly such as for a deprecated Operator, to keep the supportability wording consistent across deprecated features. Provide a value for the :FeatureName: variable before you include this module.

See an example of how this is applied.

Verification of your content

All documentation changes must be verified by a QE team associate before merging. This includes executing all "Procedure" changes and confirming expected results. There are exceptions for typo-level changes, formatting-only changes, and other negotiated documentation sets and distributions.

If a documentation change is due to a Bugzilla bug or Jira issue, the bug/issue should be put on ON_QA when you have a PR ready. After QE approval is given (either in the bug/issue or in the PR), the QE associate should move the bug/issue status to VERIFIED, at which point the associated PR can be merged. It is also ok for the assigned writer to change the status of the bug/issue to VERIFIED if approval for the changes has been provided in another forum (slack, PR, or email). The writer should indicate that the QE team approved the change as a comment in the bug/issue.

Images

Block images

To include a block image (an image on its own line):

  1. Put the image file in the images folder.

    Ensure that the folder containing your assembly contains an images symbolic link to the top-level images/ directory, otherwise the image will not be found when building the docs.

  2. In the .adoc content, use this format to link to the image:

    image::<image_filename>[<alt_text>]

    Note the double :: instead of a single :, as seen in inline image usage. You only have to specify <image_filename> itself and not the full file path; the build mechanism automatically expands this appropriately.

Inline images (icons)

Inline images can be used to indicate graphic items in the web console, such as buttons or menu icons.

Inserting reusable images inline

To simplify reuse, the following common SVGs (the OpenShift web console uses the Font Awesome icon set) have already been added to the images folder with a user-defined entity added to the common-attributes.adoc module:

Icon Entity Alt text File name

Kebab

:kebab:

Options menu

ellipsis-v.svg

When using inline, include the image after the UI element name. For example:

Click the *Options* menu {kebab}.

Inserting images inline without reuse

If you are inserting an image that is not part of the common-attributes.adoc module, then include the image using this formatting:

image:<image_filename>[title="<alt_text>"]

Note the single : instead of a double ::, as seen in block image usage.

For example:

image:manage-columns.png[title="Manage Columns icon"]

Formatting

For all of the system blocks including table delimiters, use four characters. For example:

|=== for tables
---- for code blocks
Note

You can use backticks or other markup in the title for a block, such as a code block .Example or a table .Description title.

Code blocks, command syntax, and example output

Code blocks are generally used to show examples of command syntax, example screen output, and configuration files.

The main distinction between showing command syntax and a command example is that a command syntax shows readers how to use the command without real values. An example command, however, shows the command with actual values with an example output of that command, where applicable.

For example:

In the following example, the `oc get` operation returns a complete list of services that are currently defined:

[source,terminal]
----
$ oc get se
----

.Example output
[source,terminal]
----
NAME                LABELS                                    SELECTOR            IP                  PORT
kubernetes          component=apiserver,provider=kubernetes   <none>              172.30.17.96        443
kubernetes-ro       component=apiserver,provider=kubernetes   <none>              172.30.17.77        80
docker-registry     <none>                                    name=registrypod    172.30.17.158       5001
----

This renders as:

In the following example, the oc get operation returns a complete list of services that are currently defined:

$ oc get se
Example output
NAME                LABELS                                    SELECTOR            IP                  PORT
kubernetes          component=apiserver,provider=kubernetes   <none>              172.30.17.96        443
kubernetes-ro       component=apiserver,provider=kubernetes   <none>              172.30.17.77        80
docker-registry     <none>                                    name=registrypod    172.30.17.158       5001

The following guidelines go into more detail about specific requirements and recommendations when using code blocks:

  • If a step in a procedure is to run a command, make sure that the step text includes an explicit instruction to "run" or "enter" the command. In most cases, use one of the following patterns to introduce the code block:

    • <Step description>, run the following command:

    • <Step description>, enter the following command:

  • Do NOT use any markup in code blocks; code blocks generally do not accept any markup.

  • For all code blocks, you must include an empty line above a code block (unless that line is introducing block metadata, such as [source,terminal] for syntax highlighting).

    Acceptable:

    Lorem ipsum
    
    ----
    $ lorem.sh
    ----

    Not acceptable:

    Lorem ipsum
    ----
    $ lorem.sh
    ----

    Without the line spaces, the content is likely to be not parsed correctly.

  • Use [source,terminal] for oc commands or any terminal commands to enable syntax highlighting. Any [source] metadata must go on the line directly before the code block. For example:

    [source,terminal]
    ----
    $ oc get nodes
    ----

    If you are also showing a code block for the output of the command, use [source,terminal] for that code block as well.

  • Use source tags for the programming language used in the code block to enable syntax highlighting. For example:

    • [source,yaml]

    • [source,go]

    • [source,javascript]

  • Do not use more than one command per code block. For example, the following must be split up into three separate code blocks:

    To create templates you can modify, run the following commands :
    
    [source,terminal]
    ----
    $ oc adm create-login-template > login.html
    ----
    
    [source,terminal]
    ----
    $ oc adm create-provider-selection-template > providers.html
    ----
    
    [source,terminal]
    ----
    $ oc adm create-error-template > errors.html
    ----
  • Separate a command and its related example output into individual code blocks. This allows the command to be easily copied using the button on docs.openshift.com.

    In addition, prepend the code block for the output with the title .Example output to make it consistently clear across the docs when this is being represented. A lead-in sentence explaining the example output is optional. For example:

    Use the `oc new-project` command to create a new project:
    
    [source,terminal]
    ----
    $ oc new-project my-project
    ----
    
    The output verifies that a new project was created:
    
    .Example output
    [source,terminal]
    ----
    Now using project "my-project" on server "https://openshift.example.com:6443".
    ----
  • To mark up command syntax, use the code block and wrap any replaceable values in angle brackets (<>) with the required command parameter, using underscores (_) between words as necessary for legibility. For example:

    To view a list of objects for the specified object type, enter the following command:
    
    [source,terminal]
    ----
    $ oc get <object_type> <object_id>
    ----

    This renders as:

    To view a list of objects for the specified object type, enter the following command:

    $ oc get <object_type> <object_id>
    Note
    Avoid using full command syntax inline with sentences.
  • If you must provide additional information on what a line of a code block represents, use callouts (<1>, <2>, etc.) to provide that information.

    Use this format when embedding callouts into the code block:

    ----
    code example 1 <1>
    code example 2 <2>
    ----
    <1> A note about the first example value.
    <2> A note about the second example value.
  • If you must provide additional information on what a line of a code block represents and the use of callouts is impractical, you can use a description list to provide information about the variables in the code block. Using callouts might be impractical if a code block contains too many conditional statements to easily use numbered callouts or if the same note applies to multiple lines of the codeblock.

    ----
    code <variable_1>
    code <variable_2>
    ----
    +
    where:
    
    <variable_1>:: Specifies the explanation of the first variable.
    <variable_2>:: Specifies the explanation of the first variable.

    Be sure to introduce the description list with "where:" and start each variable description with "Specifies."

  • For long lines of code that you want to break up among multiple lines, use a backslash to show the line break. For example:

    $ oc get endpoints --all-namespaces --template \
        '{{ range .items }}{{ .metadata.namespace }}:{{ .metadata.name }} \
        {{ range .subsets }}{{ range .addresses }}{{ .ip }} \
        {{ end }}{{ end }}{{ "\n" }}{{ end }}' | awk '/ 172\.30\./ { print $1 }'
  • If the user must run a command as root, use a number sign (#) at the start of the command instead of a dollar sign ($). For example:

    # subscription-manager list
  • For snippets or sections of a file, use an ellipsis (…​) to show that the file continues before and/or after the quoted block.

    apiVersion: v1
    kind: Pod
    metadata:
      labels:
        test: liveness
    ...

    or

    Name:               ci-ln-iyhx092-f76d1-nvdfm-worker-b-wln2l
    Roles:              worker
    ...
    Taints:             node-role.kubernetes.io/infra:NoSchedule
    ...

    Do not use […​], <snip>, or any other variant.

  • Do not use jq in commands (unless it is truly required), because this requires users to install the jq tool. Oftentimes, the same or similar result can be accomplished using jsonpath for oc commands.

    For example, this command that uses jq:

    $ oc get clusterversion -o json|jq ".items[0].spec"

    can be updated to use jsonpath instead:

    $ oc get clusterversion -o jsonpath='{.items[0].spec}{"\n"}'
  • For Bash "here" documents use [source,terminal], such as the following example:

    [source,terminal]
    ----
    $ cat <<EOF| oc create -f -
    apiVersion: v1
    kind: Pod
    metadata:
      name: mlistener
      labels:
        app: multicast-verify
    EOF
    ----
  • For the output of commands use [source,text], such as with the following example output from the oc describe <pural> <object> command:

    [source,text]
    ----
    Name:               node1.example.com
    Roles:              worker
    Labels:             beta.kubernetes.io/arch=amd64
    ...
    Annotations:        cluster.k8s.io/machine: openshift-machine-api/ahardin-worker-us-east-2a-q5dzc
    ...
    CreationTimestamp:  Wed, 13 Feb 2019 11:05:57 -0500
    ----

YAML formatting for Kubernetes and OpenShift API objects

The following formatting guidelines apply to YAML manifests, but do not apply to the installation configuration YAML specified by install-config.yaml.

When possible, ensure that YAML is valid in a running cluster. You can validate YAML with oc apply with the following invocation:

$ oc apply -f test.yaml --dry-run=client

Required fields

  • Include the apiVersion and kind so that a user always knows the context of the YAML.

  • Include the full hierarchy to a deeply nested key.

  • For objects that are in the global scope, such as for config.openshift.io API group, always include the metadata.name for the object, which is usually cluster.

Example API object in the global scope
apiVersion: config.openshift.io/v1
kind: Scheduler
metadata:
  name: cluster
...
spec:
  defaultNodeSelector: node-role.kubernetes.io/app=
...
Example deeply nested key with full context for .ports array
apiVersion: v1
kind: Pod
metadata:
  name: pod1
  namespace: default
spec:
  containers:
  - name: web
    image: nginx
    ports:
    - name: web
      containerPort: 80
      protocol: TCP

Formatting

Use the following conventions govern the layout of YAML for API objects.

  • Begin YAML at the beginning of the left margin.

  • Use two-space indentation.

  • Indent arrays at the same depth as the parent field.

  • Include a space immediately after the colon for keys.

  • Use block style for complex strings, such as embedded JSON or text blocks. You can enable block style by specifying | or |- after a field and indenting the field content by two spaces, such as in the following example:

    fieldName: |-
      This is a string.
      And it can be on multiple lines.
  • When truncating YAML, always precede an ellipsis with a pound so that the YAML is valid.

Example with array indentation flush with parent field
apiVersion: v1
kind: Pod
metadata:
  name: pod1
  labels:
  - key1: val1
  - key2: val2
spec:
...
Example with block string for annotation
apiVersion: v1
kind: Pod
metadata:
  name: pod1
  annotations:
    k8s.v1.cni.cncf.io/networks: |-
      [
        {
          "name": "net"
        }
      ]
spec:
...

Inline code or commands

Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.

Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks:

Use the `GET` operation to do x.

This renders as:

Use the GET operation to do x.

System messages

System messages include error, warning, confirmation, and information messages that are presented to the user in places such as the GUI, CLI, or system logs.

If a message is short enough to include inline, enclose it in back ticks:

Previously, image builds and pushes would fail with the `error reading blob from source` error message because the builder logic would compute the contents of new layers twice.

This renders as:

Previously, image builds and pushes would fail with the error reading blob from source error message because the builder logic would compute the contents of new layers twice.

If a message is too long to include inline, put it inside a code block with [source,text] metadata:

Previously, the AWS Terraform provider that the installation program used occasionally caused a race condition with the S3 bucket, and the cluster installation failed with the following error message:

[source,text]
----
When applying changes to module.bootstrap.aws_s3_bucket.ignition, provider level=error msg="\"aws\" produced an unexpected new value for was present, but now absent.
----

Now, the installation program uses different AWS Terraform provider code, which now robustly handles S3 eventual consistency, and the installer-provisioned AWS cluster installation does not fail with that error message.

This renders as:

Previously, the AWS Terraform provider that the installation program used occasionally caused a race condition with the S3 bucket, and the cluster installation failed with the following error message:

When applying changes to module.bootstrap.aws_s3_bucket.ignition, provider level=error msg="\"aws\" produced an unexpected new value for was present, but now absent.

Now, the installation program uses different AWS Terraform provider code, which now robustly handles S3 eventual consistency, and the installer-provisioned AWS cluster installation does not fail with that error message.

Note
Always refer to a message with the type of message it is, followed by the word "message". For example, refer to an error message as an "error message", and not simply as an "error".

Lists

Lists are created as shown in this example:

. Item 1 (2 spaces between the period and the first character)

. Item 2

. Item 3

This renders as:

  1. Item 1

  2. Item 2

  3. Item 3

If you must add any text, admonitions, or code blocks you have to add the continuous +, as shown in the example:

. Item 1
+
----
some code block
----

. Item 2

. Item 3

This renders as:

  1. Item 1

    some code block
  2. Item 2

  3. Item 3

Footnotes

Avoid footnotes when possible.

If you reference a footnote from only a single location, use the following syntax:

Footnote
footnote:[This is the footnote text.]

If you reference a footnote from multiple locations, set an attribute with the footnote text. As a consequence, this will duplicate the footnote text at bottom of the page.

Footnote with text set by an attribute
:note-text: This is a footnote.

This text has a footnote qualifier attached footnote:[{note-text}].

But this other text uses the same qualifier elsewhere footnote:[{note-text}].

Avoid using footnoteref.

Important

The footnoteref directive is deprecated in asciidoctor and causes a build warning when ascii_binder is run.

Footnote with reference
footnoteref:[ref-string, This is the footnote text.]

Alternative footnote styling in tables

For footnotes in tables, use the following syntax to mimic Asciidoctor’s styling:

[cols="3",options="header"]
|===
|Header 1
|Header 2
|Header 3

|Item A ^[1]^
|Item B
|Item C ^[2]^

|Item D
|Item E ^[3]^
|Item F ^[3]^
|===
[.small]
--
1. A description.
2. Another description.
3. Two items relate to this description.
--

The notes are kept immediately after the table, instead of moved to the bottom of the rendered assembly. This manual method also allows you to reuse the same footnote number for multiple references as needed.

Note the following:

  • Add a space before the superscripted numbers with square brackets.

  • To match the table cell’s font size, start the ordered list with a [.small] style and wrap it in a -- block.

Collapsible content

You can collapse sections of content by using the collapsible option, which converts the Asciidoctor markup to HTML details and summary sections. The collapsible option is used at the writer’s discretion and is appropriate for considerably long code blocks, lists, or other such content that significantly increases the length of a module or assembly.

Note

You must set a title for the summary section. If a title is not set, the default title is "Details."

Collapsible content is formatted as shown:

.Title of the `summary` dropdown
[%collapsible]
====
This is content within the `details` section.
====

This renders as a dropdown with collapsed content:

Title of the summary dropdown

This is content within the details section.

If your collapsible content includes an admonition such as a note or warning, the admonition must be nested:

.Collapsible content that includes an admonition
[%collapsible]
====
This content includes an admonition.

[source,terminal]
----
$ oc whoami
----

[NOTE]
=====
Nest admonitions when using the `collapsible` option.
=====
====

This renders as:

Collapsible content that includes an admonition

This content includes an admonition.

$ oc whoami
Note

Nest admonitions when using the collapsible option.

Quick reference

Table 1. User accounts and info
Markup in command syntax Description Substitute value in Example block

<username>

Name of user account

user@example.com

<password>

User password

password

Table 2. Projects and applications
Markup in command syntax Description Substitute value in Example block

<project>

Name of project

myproject

<app>

Name of an application

myapp

Admonitions

Admonitions such as notes and warnings are formatted as shown:

[ADMONITION]
====
Text for admonition
====

API object formatting

For terms that are API objects, the way they are written depends on whether the term is a general reference or an actual reference to the object.

General references

A general reference is any time you are speaking conceptually, or generally, about these components in a cluster.

When referring to API object terms in general usage, use lowercase and separate multi-word API objects. Default to following this guidance unless you are specifically interacting with/referring to the API object (see Object references).

For example:

  • pod

  • node

  • daemon set

  • config map

  • deployment

  • image stream

  • persistent volume claim

Examples of general references
Kubernetes runs your workload by placing containers into pods to run on nodes.

You must have at least one secret, config map, or service account.

The total number of persistent volume claims in a project.

Note that if an object uses an acronym or other special capitalization, then its general reference should honor that. For example, general references to APIService should be written as "API service", not "api service". Any other exceptions or special guidance are noted in the glossary.

Object references

An object reference is when you are referring to the actual instance of an API object, where the object name is important.

When referring to actual instances of API objects, use PascalCase and mark it up as monospace in backticks (``).

Note

Do not use backticks or other markup in assembly or module headings. You can use backticks or other markup in the title for a block, such as a code block .Example or a table .Description title.

Be sure to match the proper object type (or kind in Kubernetes terms); for example, do not add an "s" to make it plural. Only follow this guidance if you are explicitly referring to the API object (for example, when editing an object in the CLI or viewing an object in the web console).

For example:

  • Pod

  • Node

  • DaemonSet

  • ConfigMap

  • Deployment

  • ImageStream

  • PersistentVolumeClaim

Examples of API object references
After you create a `Node` object, or the kubelet on a node self-registers, the control plane checks whether the new `Node` object is valid.

The default amount of CPU that a container can use if not specified in the `Pod` spec.

Create a file, `pvc.yaml`, with the `PersistentVolumeClaim` object definition.
Note

Use "object", "resource", "custom resource", "spec", etc. as appropriate after the object reference. This helps with clarity and readability.

Another situation where this is necessary is when referring to the plural version of objects. Do not add an "s" to the end of an object name reference to make it plural. Use only the official kind of object (for example, seen when you run oc api-resources).

For example, the object kind for a node is Node, not Nodes. So do not write "You can create Nodes using kubectl." Instead, rewrite to something like "You can create Node objects using kubectl."

Operator capitalization

The term "Operator" is always capitalized. For example:

= Support policy for unmanaged Operators

Individual Operators have a `managementState` parameter in their configuration.

An Operator’s full name must be a proper noun, with each word initially capitalized. If it includes a product name, defer the product’s capitalization style guidelines. For example:

  • Red Hat OpenShift Logging Operator

  • Prometheus Operator

  • etcd Operator

  • Node Tuning Operator

  • Cluster Version Operator

Declarative config examples

Many of our procedures provide imperative oc commands (which cannot be stored in a Git repo). Due to efforts around improving the experience for GitOps users, we sometimes also want to provide a declarative YAML example that achieves the same configuration. This allows users to store these YAML configurations in a Git repo and follow GitOps practices to configure OpenShift.

Important

When adding declarative examples to procedures, do not completely replace the imperative command with the declarative YAML example. Some users might still prefer the imperative option.

To add a declarative YAML example to a procedure step with an existing imperative command, add it in a "TIP" admonition by following the template in the example below. This example uses an imperative command (oc create configmap) to create a config map, and then provides the declarative YAML example of the ConfigMap object afterward.

* Define a `ConfigMap` object containing the certificate authority by using the following command:
+
[source,terminal]
----
$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
----
+
[TIP]
====
You can alternatively apply the following YAML to create the config map:

[source,yaml]
----
apiVersion: v1
kind: ConfigMap
metadata:
  name: ca-config-map
  namespace: openshift-config
type: Opaque
data:
  ca.crt: <base64_encoded_CA_certificate_PEM>
----
====

This renders as:

  • Define a ConfigMap object containing the certificate authority by using the following command:

    $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config
    Tip

    You can alternatively apply the following YAML to create the config map:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: ca-config-map
      namespace: openshift-config
    type: Opaque
    data:
      ca.crt: <base64_encoded_CA_certificate_PEM>
Note

If you are adding a particularly long YAML block, you can optionally use the %collapsible feature to allow users to collapse the code block.

Quick markup reference

Convention Markup Example rendered output

Code blocks

Use the following syntax for the `oc` command:

----
$ oc <action> <object_type> <object_name_or_id>
----

Use the following syntax for the oc command:

$ oc <action> <object_type> <object_name_or_id>

Use backticks for all non-GUI "system items", including:

  • Inline commands, operations, literal values, variables, parameters, settings, flags, environment variables, user input

  • System term/item, user names, unique or example names for individual API objects/resources (e.g., a pod named mypod), daemon, service, or software package

  • RPM packages

  • File names or directory paths

`oc get`

Set the `upgrade` variable to `true`.

Use the `--amend` flag.

Answer by typing `Yes` or `No` when prompted.

`user_name`

`service_name`

`package_name`

`filename`

Use the oc get services command to get a list of services that are currently defined.

 

Use the --amend flag.

 

Set the upgrade variable to true.

 

Answer by typing Yes or No when prompted.

 

cluster-admin user

 

firewalld service

 

rubygems RPM package

 

The express.conf configuration file is located in the /usr/share directory.

System or software variable to be replaced by the user

`<project>`

`<deployment>`

Use the following command to roll back a Deployment, specifying the Deployment name:

oc rollback <deployment>

Use single asterisks for web console / GUI items (menus, buttons, page titles, etc.). Use two characters to form the arrow in a series of menu items (->).

Choose *Cluster Console* from the list.

Navigate to the *Operators* -> *Catalog Sources* page.

Click *Create Subscription*.

Choose Cluster Console from the list.

 

Navigate to the OperatorsCatalog Sources page.

 

Click Create Subscription.

Use underscores to emphasize the first appearance of a new term.

An _Operator_ is a method of packaging, deploying,
and managing a Kubernetes application.

An Operator is a method of packaging, deploying, and managing a Kubernetes application.

Use of underscores for general emphasis is allowed but should only be used very sparingly. Let the writing, instead of font usage, create the emphasis wherever possible.

Do _not_ delete the file.

Do not delete the file.

Footnotes

A footnote is created with the footnote macro. If you plan to reference a footnote more than once, use the ID footnoteref macro. The Customer Portal does not support spaces in the footnoteref. For example, "dynamic PV" should be "dynamicPV".

See Footnotes for the footnote and footnoteref syntax.