Skip to content

Commit f15fb71

Browse files
adellapeadellape
committed
Merge pull request openshift#1 from sosiouxme/core_concepts_reorg-deployments
Core concepts reorg -- deployments
2 parents 6b54467 + ebdf1b5 commit f15fb71

File tree

4 files changed

+223
-51
lines changed

4 files changed

+223
-51
lines changed

‎architecture/core_concepts/containers_and_images.adoc

+113-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
= Containers and Images
1+
= Overview
22
{product-author}
33
{product-version}
44
:data-uri:
@@ -11,3 +11,115 @@
1111
toc::[]
1212

1313
== Containers
14+
15+
The basic units of OpenShift applications are called containers. Linux
16+
container technologies are lightweight mechanisms for isolating
17+
running processes so that they are limited to interacting with only
18+
their designated resources. Many application instances can be running
19+
in containers on a single host without visibility into each others'
20+
processes, files, network, and so on. Typically, each container
21+
provides a single service (often called a "micro-service"), such as a
22+
web server or a database, though containers can be used for arbitrary
23+
workloads.
24+
25+
You can read further about container technology
26+
link:https://access.redhat.com/articles/1353593[here]. The Linux kernel
27+
has been incorporating capabilities for container technologies for
28+
years. More recently the link:https://www.docker.com/whatisdocker/[Docker
29+
project] has developed a convenient management interface for Linux
30+
containers on a host. OpenShift and Kubernetes add the ability to
31+
orchestrate Docker containers across multi-host installations.
32+
33+
Though you do not directly interact with Docker tools when using
34+
OpenShift, understanding Docker's capabilities and terminology is
35+
important for understanding its role in OpenShift and how your
36+
applications function inside of containers. Docker is available
37+
as part of RHEL 7, as well as CentOS and Fedora, so you can
38+
experiment with it separately from OpenShift. Refer to the article
39+
link:https://access.redhat.com/articles/881893[Get Started with Docker
40+
Formatted Container Images on Red Hat Systems] for a guided introduction.
41+
42+
== Docker Images
43+
44+
Docker containers are based on Docker images. A Docker image is a
45+
binary that includes all of the requirements for running a single Docker
46+
container, as well as metadata describing its needs and capabilities. You
47+
can think of it as a packaging technology. Docker containers only
48+
have access to resources defined in the image, unless you give the
49+
container additional access when creating it. By deploying the same
50+
image in multiple containers across multiple hosts and load balancing
51+
between them, OpenShift can provide redundancy and horizontal scaling
52+
for a service packaged into an image.
53+
54+
You can use Docker directly to build images, but OpenShift also supplies
55+
builders that assist with creating an image by adding your code or
56+
configuration to existing images.
57+
58+
Since applications develop over time, a single image name can actually
59+
refer to many different versions of the "same" image. Each different
60+
image is referred to uniquely by its hash (a long hexadecimal number
61+
e.g. `fd44297e2ddb050ec4f...`) which is usually shortened to 12
62+
characters (e.g. `fd44297e2ddb`). Rather than version numbers, Docker
63+
allows applying tags (such as `v1`, `v2.1`, `GA`, or the default `latest`)
64+
in addition to the image name to further specify the image desired, so
65+
you may see the same image referred to as `centos` (implying the `latest`
66+
tag), `centos:centos7`, or `fd44297e2ddb`.
67+
68+
== Docker registries
69+
70+
A Docker registry is a Docker image repository: a service
71+
for storing and retrieving Docker images. The most famous is the
72+
link:https://registry.hub.docker.com/[Docker Hub], but Docker may also use
73+
private or third-party repositories. Red Hat provides a Docker registry at
74+
`registry.access.redhat.com` for subscribers. OpenShift can also supply
75+
its own internal registry for managing custom Docker images.
76+
77+
The relationship between Docker containers, images, and registries is
78+
depicted in the following diagram:
79+
80+
[ditaa, "docker-diagram"]
81+
----
82+
83+
+---------+ +--------------------------------------+
84+
| Built | | Registry service |
85+
| image | docker push | |
86+
| "myapp" +-------------> | +-------------+ +--------+ |
87+
| | | | myapp:v0.1 | | image2 | ... |
88+
+---------+ | | +------------+ +--------+ |
89+
| | | myapp:v0.2 | |
90+
| +--| +-----------+ |
91+
| +--| ... | |
92+
| +-----------+ |
93+
| |
94+
+------------------+-------------------+
95+
:
96+
| docker pull
97+
|
98+
+-----------------------+---------+------------------ ...
99+
| |
100+
| |
101+
v v
102+
+------------------------+ +------------------------+
103+
| | | |
104+
| /-------------------\ | | /-------------------\ |
105+
| | Container 1 | | | | Container 1 | |
106+
| | +--------------+ | | | | +--------------+ | |
107+
| | | myapp:latest | | | | | | myapp:latest | | |
108+
| | +--------------+ | | | | +--------------+ | |
109+
| \-------------------/ | | \-------------------/ |
110+
| | | |
111+
| /-------------------\ | | /-------------------\ |
112+
| | Container 2 | | | | Container 2 | |
113+
| | +--------------+ | | | | +--------------+ | |
114+
| | | image2 | | | | | | image3 | | |
115+
| | +--------------+ | | | | +--------------+ | |
116+
| \-------------------/ | | \-------------------/ |
117+
| | | |
118+
| ... | | ... |
119+
| | | |
120+
| Host 1 | | Host 2 | ...
121+
+------------------------+ +------------------------+
122+
123+
124+
125+
----

‎architecture/core_concepts/deployments.adoc

+106-50
Original file line numberDiff line numberDiff line change
@@ -10,65 +10,121 @@
1010

1111
toc::[]
1212

13-
== Deployments
14-
See link:../../dev_guide/deployments.html[Deployments].
13+
== Replication Controllers
1514

16-
== Deployment Configurations
17-
See link:../../dev_guide/deployments.html[Deployments].
15+
A replication controller ensures that a specified number of replicas of a pod
16+
are running at all times. If pods exit or are deleted, the replica controller
17+
acts to instantiate more up to the desired number. Likewise, if there are more
18+
running than desired, it deletes as many as necessary to match the number.
1819

19-
== Replication Controllers
20+
The definition of a replication controller consists mainly of:
21+
22+
1. The number of replicas desired (which can be adjusted at runtime).
23+
2. A pod definition for creating a replicated pod.
24+
3. A selector for identifying managed pods.
2025

21-
A replication controller ensures that a specific number of pods set with a
22-
particular label are running at all times. If one of the matching pods or a
23-
Kubernetes host goes down, the replication controller re-instantiates matching
24-
pods up to the defined number across the cluster. Likewise, if there are too
25-
many running pods, it kills the required amount of hosts. Any new pods are
26-
created by the template set in the replication controller object.
26+
The selector is just a set of labels that all of the pods managed by the
27+
replication controller should have. So that set of labels is included
28+
in the pod definition that the replication controller instantiates.
29+
This selector is used by the replication controller to determine how many
30+
instances of the pod are already running in order to adjust as needed.
2731

28-
The replication controller does not perform auto-scaling; rather, it is
29-
controlled by an external auto-scaler, which changes the `*replicas*` field.
30-
Replication controllers are only appropriate for pods with `*restartPolicy*` set
31-
to *Always*, and a pod with a different restart policy is refused.
32+
It is not the job of the replication controller to perform auto-scaling
33+
based on load or traffic, as it does not track either; rather, this
34+
would require its replica count to be adjusted by an external auto-scaler.
3235

33-
The most important elements in the structure of a replication controller object
34-
are the `*replicas*` and `*replicaSelector*` values, as shown in the following
35-
example:
36+
Replication controllers are a core Kubernetes object, `*ReplicationController*`. See the
37+
https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/replication-controller.md[Kubernetes
38+
documentation] for more on replication controllers.
3639

37-
.Replication Controller Object Definition
38-
====
40+
Here is an example `*ReplicationController*` definition with some omissions and callouts:
3941

40-
[source,json]
42+
[source,yaml]
4143
----
42-
{
43-
"kind": "ReplicationControllerList",
44-
"creationTimestamp": null,
45-
"selfLink": "/api/v1beta1/replicationControllers",
46-
"resourceVersion": 27,
47-
"apiVersion": "v1beta1",
48-
"items": [
49-
{
50-
"id": "docker-registry-1",
51-
"uid": "7fa58610-9b31-11e4-9dff-f0def1de880f",
52-
"creationTimestamp": "2015-01-13T09:36:02-05:00",
53-
"selfLink": "/api/v1beta1/replicationControllers/docker-registry-1?namespace=default",
54-
"resourceVersion": 26,
55-
"namespace": "default",
56-
"annotations": {
57-
...
58-
},
59-
"desiredState": {
60-
"replicas": 1, <1>
61-
"replicaSelector": {
62-
"name": "registrypod" <2>
63-
},
44+
apiVersion: v1
45+
kind: ReplicationController
46+
metadata:
47+
name: frontend-1
48+
spec:
49+
replicas: 1 <1>
50+
selector: <2>
51+
name: frontend
52+
template: <3>
53+
metadata:
54+
labels: <4>
55+
name: frontend
56+
spec:
57+
containers:
58+
- image: openshift/hello-openshift
59+
name: helloworld
60+
ports:
61+
- containerPort: 8080
62+
protocol: TCP
63+
restartPolicy: Always
6464
----
65-
<1> The number of copies of the pod to run.
66-
<2> The label selector of the pod to run.
6765

68-
====
66+
1. The number of copies of the pod to run.
67+
2. The label selector of the pod to run.
68+
3. A template for the pod the controller creates.
69+
4. Labels on the pod should include those from the label selector.
6970

70-
These determine which pods to maintain.
71+
== Deployments and Deployment Configurations
72+
73+
Building on replication controllers, OpenShift adds expanded support
74+
for the software development and deployment lifecycle with the concept
75+
of deployments. In the simplest case, a deployment just creates a new
76+
replication controller and lets it start up pods. However, OpenShift
77+
deployments also provide the ability to transition from an existing
78+
deployment of an image to a new one and also define hooks to be run
79+
before or after creating the replication controller.
80+
81+
The OpenShift DeploymentConfiguration object defines the following details of a deployment:
82+
83+
1. The elements of a `*ReplicationController*` definition.
84+
2. Triggers for creating a new deployment automatically.
85+
3. The strategy for transitioning between deployments.
86+
4. Life cycle hooks.
87+
88+
Each time a deployment is triggered, whether manually or automatically,
89+
a deployer pod manages the deployment (including scaling down the old
90+
replication controller, scaling up the new one, and running hooks).
91+
The deployment pod remains for an indefinite amount of time after it
92+
completes the deployment in order to retain its logs of the deployment.
93+
When a deployment is superseded by another, the previous replication
94+
controller is retained to enable easy rollback if needed.
95+
96+
For detailed instructions on how to create and interact with deployments,
97+
refer to link:../../dev_guide/deployments.html[Deployments].
98+
99+
Here is an example `*DeploymentConfiguration*` definition with some
100+
omissions and callouts:
101+
102+
[source,yaml]
103+
----
104+
apiVersion: v1
105+
kind: DeploymentConfig
106+
metadata:
107+
name: frontend
108+
spec:
109+
replicas: 5
110+
selector:
111+
name: frontend
112+
template: { ... }
113+
triggers:
114+
- type: ConfigChange <1>
115+
- imageChangeParams:
116+
automatic: true
117+
containerNames:
118+
- helloworld
119+
from:
120+
kind: ImageStreamTag
121+
name: hello-openshift:latest
122+
type: ImageChange <2>
123+
strategy:
124+
type: Rolling <3>
125+
----
126+
127+
1. A `*ConfigChange*` trigger causes a new deployment to be created any time the replication controller template changes.
128+
2. An `*ImageChange*` trigger causes a new deployment to be created each time a new version of the backing image is available in the named image stream.
129+
3. The default `*Rolling*` strategy makes a downtime-free transition between deployments.
71130

72-
See the
73-
https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/replication-controller.md[Kubernetes
74-
documentation] for more on replication controllers.

‎architecture/core_concepts/images/docker-diagram.png

18.4 KB
Loading

‎contributing_to_docs/tools_and_setup.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,10 @@ $ cd openshift-docs
7070
$ bundle install
7171
----
7272

73+
This installs the Ruby gems required for the build. Some may have further dependencies that need to be installed on your system. For instance,
74+
`rjb` requires $JAVA_HOME be set, which requires a JDK installed (try e.g. `yum install java-1.8.0-openjdk-devel` and `export JAVA_HOME=/usr/lib/jvm/java-1.8.0`).
75+
You can simply rerun the `bundle install` command to continue after adding any necessary dependencies.
76+
7377
=== How to use LiveReload
7478
With the initial setup complete, you are ready to use LiveReload to edit your content.
7579

0 commit comments

Comments
 (0)