Skip to content

Commit

Permalink
Revamps to "Core Concepts" topics
Browse files Browse the repository at this point in the history 
setup: notes about gem dependencies
arch core deployments: total revamp
arch core: docker diagram and changes
arch core: projects and users revamped
arch core: overhaul pods and services
  • Loading branch information
@sosiouxme @adellape
sosiouxme authored and adellape committed Jun 22, 2015
1 parent 5da9ab5 commit 4c2c1ca
Show file tree
Hide file tree
Showing 6 changed files with 469 additions and 271 deletions.
114 changes: 113 additions & 1 deletion architecture/core_concepts/containers_and_images.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
= Containers and Images
= Overview
{product-author}
{product-version}
:data-uri:
Expand All @@ -11,3 +11,115 @@
toc::[]

== Containers

The basic units of OpenShift applications are called containers. Linux
container technologies are lightweight mechanisms for isolating
running processes so that they are limited to interacting with only
their designated resources. Many application instances can be running
in containers on a single host without visibility into each others'
processes, files, network, and so on. Typically, each container
provides a single service (often called a "micro-service"), such as a
web server or a database, though containers can be used for arbitrary
workloads.

You can read further about container technology
link:https://access.redhat.com/articles/1353593[here]. The Linux kernel
has been incorporating capabilities for container technologies for
years. More recently the link:https://www.docker.com/whatisdocker/[Docker
project] has developed a convenient management interface for Linux
containers on a host. OpenShift and Kubernetes add the ability to
orchestrate Docker containers across multi-host installations.

Though you do not directly interact with Docker tools when using
OpenShift, understanding Docker's capabilities and terminology is
important for understanding its role in OpenShift and how your
applications function inside of containers. Docker is available
as part of RHEL 7, as well as CentOS and Fedora, so you can
experiment with it separately from OpenShift. Refer to the article
link:https://access.redhat.com/articles/881893[Get Started with Docker
Formatted Container Images on Red Hat Systems] for a guided introduction.

== Docker Images

Docker containers are based on Docker images. A Docker image is a
binary that includes all of the requirements for running a single Docker
container, as well as metadata describing its needs and capabilities. You
can think of it as a packaging technology. Docker containers only
have access to resources defined in the image, unless you give the
container additional access when creating it. By deploying the same
image in multiple containers across multiple hosts and load balancing
between them, OpenShift can provide redundancy and horizontal scaling
for a service packaged into an image.

You can use Docker directly to build images, but OpenShift also supplies
builders that assist with creating an image by adding your code or
configuration to existing images.

Since applications develop over time, a single image name can actually
refer to many different versions of the "same" image. Each different
image is referred to uniquely by its hash (a long hexadecimal number
e.g. `fd44297e2ddb050ec4f...`) which is usually shortened to 12
characters (e.g. `fd44297e2ddb`). Rather than version numbers, Docker
allows applying tags (such as `v1`, `v2.1`, `GA`, or the default `latest`)
in addition to the image name to further specify the image desired, so
you may see the same image referred to as `centos` (implying the `latest`
tag), `centos:centos7`, or `fd44297e2ddb`.

== Docker registries

A Docker registry is a Docker image repository: a service
for storing and retrieving Docker images. The most famous is the
link:https://registry.hub.docker.com/[Docker Hub], but Docker may also use
private or third-party repositories. Red Hat provides a Docker registry at
`registry.access.redhat.com` for subscribers. OpenShift can also supply
its own internal registry for managing custom Docker images.

The relationship between Docker containers, images, and registries is
depicted in the following diagram:

[ditaa, "docker-diagram"]
----
+---------+ +--------------------------------------+
| Built | | Registry service |
| image | docker push | |
| "myapp" +-------------> | +-------------+ +--------+ |
| | | | myapp:v0.1 | | image2 | ... |
+---------+ | | +------------+ +--------+ |
| | | myapp:v0.2 | |
| +--| +-----------+ |
| +--| ... | |
| +-----------+ |
| |
+------------------+-------------------+
:
| docker pull
|
+-----------------------+---------+------------------ ...
| |
| |
v v
+------------------------+ +------------------------+
| | | |
| /-------------------\ | | /-------------------\ |
| | Container 1 | | | | Container 1 | |
| | +--------------+ | | | | +--------------+ | |
| | | myapp:latest | | | | | | myapp:latest | | |
| | +--------------+ | | | | +--------------+ | |
| \-------------------/ | | \-------------------/ |
| | | |
| /-------------------\ | | /-------------------\ |
| | Container 2 | | | | Container 2 | |
| | +--------------+ | | | | +--------------+ | |
| | | image2 | | | | | | image3 | | |
| | +--------------+ | | | | +--------------+ | |
| \-------------------/ | | \-------------------/ |
| | | |
| ... | | ... |
| | | |
| Host 1 | | Host 2 | ...
+------------------------+ +------------------------+
----
156 changes: 106 additions & 50 deletions architecture/core_concepts/deployments.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,65 +10,121 @@

toc::[]

== Deployments
See link:../../dev_guide/deployments.html[Deployments].
== Replication Controllers

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

== Replication Controllers
The definition of a replication controller consists mainly of:

1. The number of replicas desired (which can be adjusted at runtime).
2. A pod definition for creating a replicated pod.
3. A selector for identifying managed pods.

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

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

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

.Replication Controller Object Definition
====
Here is an example `*ReplicationController*` definition with some omissions and callouts:

[source,json]
[source,yaml]
----
{
"kind": "ReplicationControllerList",
"creationTimestamp": null,
"selfLink": "/api/v1beta1/replicationControllers",
"resourceVersion": 27,
"apiVersion": "v1beta1",
"items": [
{
"id": "docker-registry-1",
"uid": "7fa58610-9b31-11e4-9dff-f0def1de880f",
"creationTimestamp": "2015-01-13T09:36:02-05:00",
"selfLink": "/api/v1beta1/replicationControllers/docker-registry-1?namespace=default",
"resourceVersion": 26,
"namespace": "default",
"annotations": {
...
},
"desiredState": {
"replicas": 1, <1>
"replicaSelector": {
"name": "registrypod" <2>
},
apiVersion: v1
kind: ReplicationController
metadata:
name: frontend-1
spec:
replicas: 1 <1>
selector: <2>
name: frontend
template: <3>
metadata:
labels: <4>
name: frontend
spec:
containers:
- image: openshift/hello-openshift
name: helloworld
ports:
- containerPort: 8080
protocol: TCP
restartPolicy: Always
----
<1> The number of copies of the pod to run.
<2> The label selector of the pod to run.

====
1. The number of copies of the pod to run.
2. The label selector of the pod to run.
3. A template for the pod the controller creates.
4. Labels on the pod should include those from the label selector.

These determine which pods to maintain.
== Deployments and Deployment Configurations

Building on replication controllers, OpenShift adds expanded support
for the software development and deployment lifecycle with the concept
of deployments. In the simplest case, a deployment just creates a new
replication controller and lets it start up pods. However, OpenShift
deployments also provide the ability to transition from an existing
deployment of an image to a new one and also define hooks to be run
before or after creating the replication controller.

The OpenShift DeploymentConfiguration object defines the following details of a deployment:

1. The elements of a `*ReplicationController*` definition.
2. Triggers for creating a new deployment automatically.
3. The strategy for transitioning between deployments.
4. Life cycle hooks.

Each time a deployment is triggered, whether manually or automatically,
a deployer pod manages the deployment (including scaling down the old
replication controller, scaling up the new one, and running hooks).
The deployment pod remains for an indefinite amount of time after it
completes the deployment in order to retain its logs of the deployment.
When a deployment is superseded by another, the previous replication
controller is retained to enable easy rollback if needed.

For detailed instructions on how to create and interact with deployments,
refer to link:../../dev_guide/deployments.html[Deployments].

Here is an example `*DeploymentConfiguration*` definition with some
omissions and callouts:

[source,yaml]
----
apiVersion: v1
kind: DeploymentConfig
metadata:
name: frontend
spec:
replicas: 5
selector:
name: frontend
template: { ... }
triggers:
- type: ConfigChange <1>
- imageChangeParams:
automatic: true
containerNames:
- helloworld
from:
kind: ImageStreamTag
name: hello-openshift:latest
type: ImageChange <2>
strategy:
type: Rolling <3>
----

1. A `*ConfigChange*` trigger causes a new deployment to be created any time the replication controller template changes.
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.
3. The default `*Rolling*` strategy makes a downtime-free transition between deployments.

See the
https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/replication-controller.md[Kubernetes
documentation] for more on replication controllers.
Binary file added architecture/core_concepts/images/docker-diagram.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 4c2c1ca

Please sign in to comment.