Migration: Master Creating Images

Author: vikram-redhat

creating_images/custom.adoc

@@ -13,7 +13,7 @@ toc::[]
 == Overview
 By allowing you to define a specific builder image responsible for the entire
 build process, {product-title}'s
-link:../dev_guide/builds.html#custom-strategy-options[Custom build strategy] was
+xref:../dev_guide/builds.adoc#custom-strategy-options[Custom build strategy] was
 designed to fill a gap created with the increased popularity of creating Docker
 images. When there is a requirement for a build to still produce individual
 artifacts (packages, JARs, WARs, installable ZIPs, and base images, for
@@ -48,10 +48,10 @@ variables with the information needed to proceed with the build:
 
 |`*BUILD*`
 |The entire serialized JSON of the `*Build*`
-link:../rest_api/openshift_v1.html#v1-build[object definition]. If you need to
+xref:../rest_api/openshift_v1.adoc#v1-build[object definition]. If you need to
 use a specific API version for serialization, you can set the
 `*buildAPIVersion*` parameter in the
-link:../dev_guide/builds.html#custom-strategy-options[custom strategy
+xref:../dev_guide/builds.adoc#custom-strategy-options[custom strategy
 specification] of the build configuration.
 
 |`*SOURCE_REPOSITORY*`
@@ -101,10 +101,10 @@ Although Custom builder image authors have great flexibility in defining the
 build process, your builder image must still adhere to the following required
 steps necessary for seamlessly running a build inside of {product-title}:
 
-. Read the `*Build*` link:../rest_api/openshift_v1.html#v1-build[object
+. Read the `*Build*` xref:../rest_api/openshift_v1.adoc#v1-build[object
 definition], which contains all the necessary information about input parameters
 for the build.
 . Run the build process.
 . If your build produces an image, push it to the build's
-link:../rest_api/openshift_v1.html#v1-buildoutput[output location] if it is
+xref:../rest_api/openshift_v1.adoc#v1-buildoutput[output location] if it is
 defined. Other output locations can be passed with environment variables.

creating_images/guidelines.adoc

@@ -186,7 +186,7 @@ It is best to avoid setting default passwords. Many people will extend the image
 and forget to remove or change the default password. This can lead to security
 issues if a user in production is assigned a well-known password. Passwords
 should be configurable using an environment variable instead. See the
-link:#use-env-vars[Using Environment Variables for Configuration] topic for more
+xref:use-env-vars[Using Environment Variables for Configuration] topic for more
 information.
 
 If you do choose to set a default password, ensure that an appropriate warning
@@ -261,7 +261,7 @@ For example, this https://github.com/openshift/sti-python[Python image]
 defines S2I scripts for building various versions of Python applications.
 
 For more details about how to write S2I scripts for your image, see the
-link:s2i.html[S2I Requirements] topic.
+xref:s2i.adoc#creating-images-s2i[S2I Requirements] topic.
 
 [[use-uid]]
 *Support Arbitrary User IDs*
@@ -343,7 +343,7 @@ validate the authority the image is attempting to run with and prevent running
 images that are trying to run as root, because running containers as a
 privileged user exposes
 ifdef::openshift-enterprise,openshift-origin[]
-link:../install_config/install/prerequisites.html#security-warning[potential
+xref:../install_config/install/prerequisites.adoc#security-warning[potential
 security holes].
 endif::[]
 ifdef::openshift-dedicated[]
@@ -358,11 +358,11 @@ ifdef::openshift-enterprise,openshift-origin[]
 If your S2I image does not include a *USER* declaration with a numeric user,
 your builds will fail by default. In order to allow images that use either named
 users or the root (*0*) user to build in {product-title}, you can
-link:../admin_guide/manage_scc.html#grant-access-to-the-privileged-scc[add the
+xref:../admin_guide/manage_scc.adoc#grant-access-to-the-privileged-scc[add the
 project's builder service account]
 (*system:serviceaccount:<your-project>:builder*) to the *privileged* security
 context constraint (SCC). Alternatively, you can allow all images to
-link:../admin_guide/manage_scc.html#enable-images-to-run-with-user-in-the-dockerfile[run
+xref:../admin_guide/manage_scc.adoc#enable-images-to-run-with-user-in-the-dockerfile[run
 as any user].
 ====
 endif::[]
@@ -373,7 +373,7 @@ endif::[]
 For cases where your image needs to communicate with a service provided by
 another image, such as a web front end image that needs to access a database
 image to store and retrieve data, your image should consume an {product-title}
-link:../architecture/core_concepts/pods_and_services.html#services[service].
+xref:../architecture/core_concepts/pods_and_services.adoc#services[service].
 Services provide a static endpoint for access which does not change as
 containers are stopped, started, or moved. In addition, services provide load
 balancing for requests.
@@ -422,7 +422,7 @@ volumes that would be mounted into the container at runtime. However, if you
 elect to do it this way you must ensure that your image provides clear error
 messages on startup when the necessary volume or configuration is not present.
 
-This topic is related to the link:#use-services[Using Services for Inter-image
+This topic is related to the xref:use-services[Using Services for Inter-image
 Communication] topic in that configuration like datasources should be defined in
 terms of environment variables that provide the service endpoint information.
 This allows an application to dynamically consume a datasource service that is
@@ -449,7 +449,7 @@ allowing {product-title} to create a better experience for developers using your
 image. For example, you can add metadata to provide helpful descriptions of your
 image, or offer suggestions on other images that may also be needed.
 
-See the link:metadata.html[Image Metadata] topic for more information on
+See the xref:metadata.adoc#creating-images-metadata[Image Metadata] topic for more information on
 supported metadata and how to define them.
 
 *Clustering*
@@ -478,18 +478,18 @@ running container and retrieve or view the log file.
 *Liveness and Readiness Probes*
 
 Document example
-link:../dev_guide/application_health.html#container-health-checks-using-probes[liveness
+xref:../dev_guide/application_health.adoc#container-health-checks-using-probes[liveness
 and readiness probes] that can be used with your image. These probes will allow
 users to deploy your image with confidence that traffic will not be routed to
 the container until it is prepared to handle it, and that the container will be
 restarted if the process gets into an unhealthy state.
 
 *Templates*
 
-Consider providing an example link:../dev_guide/templates.html[template] with
+Consider providing an example xref:../dev_guide/templates.adoc#dev-guide-templates[template] with
 your image. A template will give users an easy way to quickly get your image
 deployed with a working configuration. Your template should include the
-link:../dev_guide/application_health.html#container-health-checks-using-probes[liveness
+xref:../dev_guide/application_health.adoc#container-health-checks-using-probes[liveness
 and readiness probes] you documented with the image, for completeness.
 
 

creating_images/index.adoc

@@ -9,5 +9,5 @@
 This guide provides best practices on writing and testing Docker images that can be used on {product-title}.
 ifdef::openshift-enterprise,openshift-origin[]
 Once you have created an image, you can push it to
-the link:../install_config/install/docker_registry.html[internal registry].
+the xref:../install_config/install/docker_registry.adoc#install-config-install-docker-registry[internal registry].
 endif::[]

creating_images/s2i.adoc

@@ -11,15 +11,15 @@
 toc::[]
 
 == Overview
-link:../architecture/core_concepts/builds_and_image_streams.html#source-build[Source-to-Image
+xref:../architecture/core_concepts/builds_and_image_streams.adoc#source-build[Source-to-Image
 (S2I)] is a framework that makes it easy to write images that take application
 source code as an input and produce a new image that runs the assembled
 application as output.
 
 The main advantage of using S2I for building reproducible Docker images is the
 ease of use for developers. As a builder image author, you must understand two
 basic concepts in order for your images to provide the best possible S2I performance:
-link:#build-process[the build process] and link:#s2i-scripts[S2I scripts].
+xref:build-process[the build process] and xref:s2i-scripts[S2I scripts].
 
 [[build-process]]
 
@@ -126,7 +126,7 @@ image is working correctly. The proposed flow of that process is:
 . Run `s2i build` again to verify the *_save-artifacts_* and *_assemble_* scripts save and restore artifacts functionality. (optional)
 . Run the image to verify the test application is working.
 
-See the link:s2i_testing.html[Testing S2I Images] topic for more information.
+See the xref:s2i_testing.adoc#creating-images-s2i-testing[Testing S2I Images] topic for more information.
 
 NOTE: The suggested location to put the test application built by your
 *_test/run_* script is the *_test/test-app_* directory in your image repository.
@@ -218,11 +218,11 @@ See the https://docs.docker.com/reference/builder/#onbuild[Docker documentation]
 for more information on `ONBUILD`.
 
 Upon startup, S2I detects whether the builder image contains `sh` and `tar` binaries
-which are necessary for the S2I process to inject build inputs.  If the builder image 
+which are necessary for the S2I process to inject build inputs.  If the builder image
 does not contain these prerequisites, it will attempt to instead perform a Docker build
 to layer the inputs.  If the builder image includes `ONBUILD` instructions, S2I
 will instead fail the build because the `ONBUILD` instructions would be executed
-during the layering process, and that equate to performing a generic docker 
+during the layering process, and that equate to performing a generic docker
 build which is less secure than an S2I build and requires explicit permissions.
 
 Therefore you should ensure that your S2I builder image either does not contain

creating_images/s2i_testing.adoc

@@ -17,11 +17,11 @@ continuous integration.
 
 [NOTE]
 ====
-Check the link:s2i.html[S2I Requirements] topic to learn more about the S2I
+Check the xref:s2i.adoc#creating-images-s2i[S2I Requirements] topic to learn more about the S2I
 architecture before proceeding.
 ====
 
-As described in the link:s2i.html[S2I Requirements] topic, S2I requires the
+As described in the xref:s2i.adoc#creating-images-s2i[S2I Requirements] topic, S2I requires the
 *_assemble_* and *_run_* scripts to be present in order to successfully execute
 the S2I build. Providing the *_save-artifacts_* script reuses the build
 artifacts, and providing the *_usage_* script ensures that usage information is
@@ -148,9 +148,9 @@ platform itself as a continuous integration system. The {product-title} platform
 is capable of building Docker images and is highly customizable.
 
 To set up an S2I image builder continuous integration system, define a
-link:../architecture/core_concepts/builds_and_image_streams.html#custom-build[Custom
+xref:../architecture/core_concepts/builds_and_image_streams.adoc#custom-build[Custom
 build] and use the *openshift/sti-image-builder* image. This image executes all
-the steps mentioned in the link:#basic-testing-workflow[Basic Testing Workflow]
+the steps mentioned in the xref:basic-testing-workflow[Basic Testing Workflow]
 section and creates a new S2I builder image.
 
 .Sample `*CustomBuild*`
@@ -202,9 +202,9 @@ You can use the `oc create` command to create this `*BuildConfig*`. After you cr
 
 If your {product-title} instance is hosted on a public IP address, the build can
 be triggered each time you push into your S2I builder image GitHub repository.
-See link:../dev_guide/builds.html#webhook-triggers[webhook triggers] for more
+See xref:../dev_guide/builds.adoc#webhook-triggers[webhook triggers] for more
 information.
 
 You can also use the `*CustomBuild*` to trigger a rebuild of your application
-based on the S2I image you updated. See link:../dev_guide/builds.html#image-change-triggers[image change triggers]
+based on the S2I image you updated. See xref:../dev_guide/builds.adoc#image-change-triggers[image change triggers]
 for more information.

rest_api/openshift_v1.adoc

@@ -10171,6 +10171,7 @@ BinaryBuildSource describes a binary file to be used for the Docker and Source b
 |asFile|AsFile indicates that the provided binary input should be considered a single file within the build input. For example, specifying "webapp.war" would place the provided binary as `/webapp.war` for the builder. If left empty, the Docker and Source build strategies assume this file is a zip, tar, or tar.gz file and extract it as the source. The custom strategy receives this binary as standard input. This filename may not contain slashes or be '..' or '.'.|false|string|
 |===
 
+[[v1-build]]
 === v1.Build
 :hardbreaks:
 Build encapsulates the inputs needed to produce a new deployable image, as well as the status of the execution and a reference to the Pod which executed the build.
@@ -10266,6 +10267,7 @@ BuildLog is the (unused) resource associated with the build log redirector
 |apiVersion|APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: http://releases.k8s.io/release-1.2/docs/devel/api-conventions.md#resources|false|string|
 |===
 
+[[v1-buildoutput]]
 === v1.BuildOutput
 :hardbreaks:
 BuildOutput is input to a build strategy and describes the Docker image that the strategy should produce.