Fixing links post-restructure and related edits.

admin_guide/admin_install_openshift.adoc

@@ -8,3 +8,8 @@
 :toc-title:
 
 toc::[]
+
+If you'd like to contribute to OpenShift documentation, see our
+https://github.com/openshift/openshift-docs[source repository] and
+https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[guidelines]
+to get started.

admin_guide/manage_nodes.adoc

@@ -11,13 +11,13 @@ toc::[]
 
 == Overview
 As an OpenShift administrator, you can manage
-link:../architecture/kubernetes_infrastructure.html#node[nodes] in your instance
-using the link:cli.html[CLI].
+link:../architecture/infrastructure_components/kubernetes_infrastructure.html#node[nodes]
+in your instance using the link:../cli_reference/overview.html[CLI].
 
 When you perform node management operations, the CLI interacts with
-link:../architecture/kubernetes_infrastructure.html#node[node objects] that are
-representations of nodes. The master uses the information from node objects to
-validate nodes with health checks.
+link:../architecture/infrastructure_components/kubernetes_infrastructure.html#node[node
+objects] that are representations of nodes. The master uses the information from
+node objects to validate nodes with health checks.
 
 == Listing Nodes
 Use the following command to list all nodes that are known to your OpenShift

admin_guide/overview.adoc

@@ -4,3 +4,8 @@
 :data-uri:
 :icons:
 :experimental:
+
+If you'd like to contribute to OpenShift documentation, see our
+https://github.com/openshift/openshift-docs[source repository] and
+https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[guidelines]
+to get started.

architecture/additional_concepts/networking.adoc

@@ -9,12 +9,26 @@
 
 toc::[]
 
-Kubernetes ensures that each pod is able to network with each other, and allocates each pod an IP address from an internal network. This ensures all containers within the pod behave as if they were on the same host. Giving each pod its own IP address means that pods can be treated like physical hosts or virtual machines in terms of port allocation, networking, naming, service discovery, load balancing, application configuration, and migration.
+Kubernetes ensures that each pod is able to network with each other, and
+allocates each pod an IP address from an internal network. This ensures all
+containers within the pod behave as if they were on the same host. Giving each
+pod its own IP address means that pods can be treated like physical hosts or
+virtual machines in terms of port allocation, networking, naming, service
+discovery, load balancing, application configuration, and migration.
 
-Creating links between pods is unnecessary. However, it is not recommended that you have a pod talk to another directly by using the IP address. Instead, we recommend that you create a link:kubernetes_model.html#service[service], then interact with the service.
+Creating links between pods is unnecessary. However, it is not recommended that
+you have a pod talk to another directly by using the IP address. Instead, we
+recommend that you create a
+link:../core_objects/kubernetes_model.html#service[service], then interact with
+the service.
 
 == OpenShift SDN
 
-OpenShift deploys a software-defined networking (SDN) approach for connecting Docker containers in an OpenShift cluster. The OpenShift SDN connects all containers across all node hosts.
+OpenShift deploys a software-defined networking (SDN) approach for connecting
+Docker containers in an OpenShift cluster. The OpenShift SDN connects all
+containers across all node hosts.
 
-For the OpenShift beta releases, the OpenShift SDN is available for manual setup. See link:https://github.com/openshift/openshift-sdn[the SDN solution documentation] for more information. OpenShift SDN will be incorporated into the Ansible-based installation procedure in future versions.
+For the OpenShift beta releases, the OpenShift SDN is available for manual
+setup. See link:https://github.com/openshift/openshift-sdn[the SDN solution
+documentation] for more information. OpenShift SDN will be incorporated into the
+Ansible-based installation procedure in future versions.

architecture/additional_concepts/overview.adoc

@@ -5,3 +5,7 @@
 :icons:
 :experimental:
 
+If you'd like to contribute to OpenShift documentation, see our
+https://github.com/openshift/openshift-docs[source repository] and
+https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[guidelines]
+to get started.

architecture/additional_concepts/port_forwarding.adoc

@@ -15,7 +15,10 @@ forwarding to pods. This is implemented using HTTP along with a multiplexed
 streaming protocol such as link:http://www.chromium.org/spdy[*SPDY*] or
 link:https://http2.github.io/[*HTTP/2*].
 
-Developers can link:../../dev_guide/port_forwarding.html[use the CLI] to port forward to a pod. The CLI listens on each local port specified by the user, forwarding via the link:../using_openshift/port_forwarding.html#protocol[described protocol].
+Developers can link:../../dev_guide/port_forwarding.html[use the CLI] to port
+forward to a pod. The CLI listens on each local port specified by the user,
+forwarding via the link:../../dev_guide/port_forwarding.html#protocol[described
+protocol].
 
 == Server Operation
 The Kubelet handles port forward requests from clients. Upon receiving a

architecture/additional_concepts/remote_commands.adoc

@@ -15,7 +15,8 @@ executing commands in containers. This is implemented using HTTP along with a
 multiplexed streaming protocol such as link:http://www.chromium.org/spdy[*SPDY*]
 or link:https://http2.github.io/[*HTTP/2*].
 
-Developers can link:../../dev_guide/executing_remote_commands.html[use the CLI] to execute remote commands in containers.
+Developers can link:../../dev_guide/executing_remote_commands.html[use the CLI]
+to execute remote commands in containers.
 
 == Server Operation
 The Kubelet handles remote execution requests from clients. Upon receiving a

architecture/core_objects/builds.adoc

@@ -15,14 +15,24 @@ A build is a process of transforming input parameters, typically source code, in
 == BuildConfig
 The `BuildConfig` object is the definition of the entire build process. It consists of the following elements:
 
-* _triggers_: Define policies used for automatically invoking builds.
-** _GitHub webhooks_: GitHub specific webhooks that specify which repository changes, such as a new commit, should invoke a new build. This trigger is specific to the GitHub API.
-** _generic webhooks_: Similar to GitHub webhooks in that they invoke a new build whenever it gets a notification. The difference is its payload is slightly different than GitHub's.
-** _image change_: Defines a trigger which is invoked upon availability of a new image in the specified ImageRepository.
-* _parameters_
-** _source_: Describes the SCM used to locate the sources. Currently only supports Git.
-** _strategy_: Describes which build type is invoked along with build type specific details.
-** _output_: Describes the resulting image name, tag, and registry to which the image should be pushed.
+[horizontal]
+triggers:: Define policies used for automatically invoking builds:
+GitHub webhooks::: GitHub specific webhooks that specify which repository
+changes, such as a new commit, should invoke a new build. This trigger is
+specific to the GitHub API.
+generic webhooks::: Similar to GitHub webhooks in that they invoke a new build
+whenever it gets a notification. The difference is its payload is slightly
+different than GitHub's.
+image change::: Defines a trigger which is invoked upon availability of a new
+image in the specified ImageRepository.
+
+parameters::
+source::: Describes the SCM used to locate the sources. Currently only supports
+Git.
+strategy::: Describes which build type is invoked along with build type specific
+details.
+output::: Describes the resulting image name, tag, and registry to which the
+image should be pushed.
 
 There are three available link:openshift_model.html#build-strategies[build strategies]:
 
@@ -38,41 +48,95 @@ Docker builds invoke the plain https://docs.docker.com/reference/commandline/cli
 
 [#sti-build]
 == STI Build
-STI builds are a replacement for the OpenShift v2-like developer experience. The developer specifies the repository where their project is located and a builder image, which defines the language and framework used for writing their application. STI then assembles a new image which runs the application defined by the source using the framework defined by the builder image.
+link:../../creating_images/sti.html[Source-to-image (STI)] is a tool for
+building reproducible Docker images. It produces ready-to-run images by
+injecting a user source into a docker image and assembling a new docker image.
+The new image incorporates the base image and built source, and is ready to use
+with the `docker run` command. STI supports incremental builds which re-use
+previously downloaded dependencies, previously built artifacts, etc.
+
+*What are the goals of STI?*
+
+[horizontal]
+Image flexibility:: STI allows you to use almost any existing Docker image as
+the base for your application. STI scripts can be written to layer application
+code onto almost any existing Docker image, so you can take advantage of the
+existing ecosystem. Note that currently STI relies on `tar` and `untar` to
+inject application source so the image needs to be able to process tarred
+content.
+
+Speed:: Adding layers as part of a *_Dockerfile_* can be slow. With STI, the
+assemble process can perform a large number of complex operations without
+creating a new layer at each step. In addition, STI scripts can be written to
+re-use dependencies stored in a previous version of the application image rather
+than re-downloading them each time the build is run.
+
+Patchability:: If an underlying image needs to be patched due to a security
+issue, OpenShift can use STI to rebuild your application on top of the patched
+builder image.
+
+Operational efficiency:: By restricting build operations instead of allowing
+arbitrary actions such as in a *_Dockerfile_*, the PaaS operator can avoid
+accidental or intentional abuses of the build system.
+
+Operational security:: Allowing users to build arbitrary an *_Dockerfile_*
+exposes the host system to root privilege escalation by a malicious user because
+the entire docker build process is run as a user with docker privileges. STI
+restricts the operations performed as a root user, and can run the scripts as an
+individual user
+
+User efficiency:: STI prevents developers from falling into a trap of performing
+arbitrary `yum install` type operations during their application build, which
+would result in slow development iteration.
+
+Ecosystem:: Encourages a shared ecosystem of images with best practices you can
+leverage for your applications.
 
 [#custom-build]
 == Custom Build
 Custom builds are the most sophisticated version of builds, allowing developers to define a builder image which is responsible for the entire process of the build. The custom builder image is a plain Docker image within which the author embeds the logic of the desired build process, such as building RPMs or building
 base Docker images.
 
 [#using-docker-credentials-for-pushing-images]
-== Using Docker credentials for pushing images
+== Using Docker Credentials for Pushing Images
 
-In case you want to push the output image into private Docker Registry that
-requires authentication or Docker Hub, you have to supply the `.dockercfg` file
-with valid Docker Registry credentials.
+In case you want to push the output image into private Docker registry that
+requires authentication or Docker Hub, you must supply a `.dockercfg` file
+with valid Docker registry credentials.
 
-The `.dockercfg` JSON file usually exists in your home directory and it has following
-format:
+The *_.dockercfg_* JSON file usually exists in your home directory and has
+following format:
 
-```
-{"https://index.docker.io/v1/":{"auth":"encrypted_password","email":"foo@bar.com"}}
-```
+====
 
-You can also add authentication entries to this file by running `docker login`
-command. The file will be created if it does not exist.
-
-The 'https://index.docker.io/v1' is the URL of the registry. You can define
-multiple Docker registries entries in this file.
-
-Kubernetes provides the https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[Secret]
-resource, which you can use to store your passwords and configuration.
-In order to make Build use your `.dockercfg` file for pushing the output image,
-you have to create the Secret first. The 'data' field in Secret must contain the
-'dockercfg' key with the value set to base64 encoded content of the '.dockercfg'
-file. For example:
-
-```
+----
+{
+	"https://index.docker.io/v1/": { <1>
+		"auth": "YWRfbGzhcGU6R2labnRib21ifTE=", <2>
+		"email": "foo@bar.com" <3>
+	}
+----
+
+<1> URL of the registry.
+<2> Encrypted password.
+<3> Email address for the login.
+====
+
+You can define multiple Docker registries entries in this file. You can also add
+authentication entries to this file by running the `docker login` command. The
+file will be created if it does not exist.
+
+Kubernetes provides the
+https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[Secret]
+resource, which you can use to store your passwords and configuration. You must
+create the `*Secret*` first before builds can use your *_.dockercfg_* file for
+pushing the output image. The `*data*` field for the `*Secret*` object must
+contain the `*dockercfg*` key with the value set to the base64-encoded content
+of the *_.dockercfg_* file. For example:
+
+====
+
+----
 {
   "apiVersion": "v1beta3",
   "kind": "Secret",
@@ -84,9 +148,19 @@ file. For example:
   }
 }
 
-```
+----
+====
+
+To create the `*Secret*` from a *_secret.json_* file, for example, you can use
+the following command:
+
+====
+
+----
+$ osc create -f secret.json
+----
+====
 
-To create the secret, you can use 'osc create -f secret.json'. Once you have
-this secret created, you can add `PushSecretName` field into `Output` section
-inside the BuildConfig and set it to the name of the Secret that you created (in
-this case 'dockerhub').
+Once you have the `*Secret*` created, you can add a `PushSecretName` field into
+`Output` section inside the `BuildConfig` and set it to the name of the
+`*Secret*` that you created, in this case `*dockerhub*`.

architecture/core_objects/openshift_model.adoc

@@ -10,39 +10,45 @@
 toc::[]
 
 == Overview
-OpenShift extends the base Kubernetes model to provide a more feature rich development lifecycle platform.
+OpenShift extends the base Kubernetes model to provide a more feature rich
+development lifecycle platform.
 
 == Build
+A link:builds.html[build] is a process of transforming input parameters,
+typically source code, into a resulting object, typically a runnable image.
 
 == BuildConfig
+A link:builds.html#buildconfig[BuildConfig] object is the definition of the
+entire link:builds.html[build] process.
 
 === Build Strategies
-The OpenShift build system provides extensible support for build strategies based on selectable types specified in the build API. By default, two strategies are supported: Docker builds, and Source-to-Image builds.
+The OpenShift build system provides extensible support for build strategies
+based on selectable types specified in the build API. By default, two strategies
+are supported: Docker builds, and Source-to-Image builds.
 
-==== Docker build
-OpenShift supports pure Docker builds. Using this strategy, users may supply a URL to a Docker context which is used as the basis for a https://docs.docker.com/reference/commandline/cli/#build[Docker build].
+*Docker Build* [[docker-build]]
 
-==== Source-to-Image
-Source-to-image (sti) is a tool for building reproducible Docker images. It produces ready-to-run images by injecting a user source into a docker image and assembling a new Docker image which incorporates the base image and built source, and is ready to use with `docker run`. STI supports incremental builds which re-use previously downloaded dependencies, previously built artifacts, etc.
+OpenShift supports pure Docker builds. Using this strategy, users may supply a
+URL to a Docker context which is used as the basis for a
+https://docs.docker.com/reference/commandline/cli/#build[Docker build].
 
-===== So why would you want to use this? There were a few goals for STI.
+*Source-to-Image (STI) Build* [[source-to-image]]
 
-* Image flexibility: STI allows you to use almost any existing Docker image as the base for your application. STI scripts can be written to layer application code onto almost any existing Docker image, so you can take advantage of the existing ecosystem. (Why only “almost” all images? Currently STI relies on tar/untar to inject application source so the image needs to be able to process tarred content.)
-* Speed: Adding layers as part of a Dockerfile can be slow. With STI the assemble process can perform a large number of complex operations without creating a new layer at each step. In addition, STI scripts can be written to re-use dependencies stored in a previous version of the application image rather than re-downloading them each time the build is run.
-* Patchability: If an underlying image needs to be patched due to a security issue, OpenShift can use STI to rebuild your application on top of the patched builder image.
-* Operational efficiency: By restricting build operations instead of allowing arbitrary actions such as in a Dockerfile, the PaaS operator can avoid accidental or intentional abuses of the build system.
-* Operational security: Allowing users to build arbitrary Dockerfiles exposes the host system to root privilege escalation by a malicious user because the entire docker build process is run as a user with docker privileges. STI restricts the operations performed as a root user, and can run the scripts as an individual user
-* User efficiency: STI prevents developers from falling into a trap of performing arbitrary “yum install” type operations during their application build, which would result in slow development iteration.
-* Ecosystem: Encourages a shared ecosystem of images with best practices you can leverage for your applications.
+link:builds.html#sti-build[STI builds] are a replacement for the OpenShift v2-like developer experience. The developer specifies the repository where their project is located and a builder image, which defines the language and framework used for writing their application. STI then assembles a new image which runs the application defined by the source using the framework defined by the builder image.
+
+*Custom Build* [[custom-build]]
 
-==== Custom build
 The custom build strategy is very similar to *Docker build* strategy, but users might customize the builder image that will be used for build execution. The Docker build uses https://registry.hub.docker.com/u/openshift/docker-builder/[openshift/docker-builder] image by default. Using your own builder image allows you to customize your build process.
 
 == BuildLog
+Logs from the containers where the build occured are accessible
+link:../../dev_guide/builds.html#accessing-build-logs[using the CLI].
 
 == Deployment
+See link:../../dev_guide/deployments.html[Deployments].
 
 == DeploymentConfig
+See link:../../dev_guide/deployments.html[Deployments].
 
 == Image
 OpenShift stores information about Docker images including the "pull spec" (what you'd use to pull the image) and complete metadata about the image (e.g. command, entrypoint, environment variables, etc.). Images in OpenShift are immutable.

architecture/core_objects/overview.adoc

@@ -5,3 +5,7 @@
 :icons:
 :experimental:
 
+If you'd like to contribute to OpenShift documentation, see our
+https://github.com/openshift/openshift-docs[source repository] and
+https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[guidelines]
+to get started.