Skip to content

Commit 1ac3751

Browse files
kalexand-rhkalexand-rh
committed
some updates per Clayton
1 parent a012bc6 commit 1ac3751

File tree

7 files changed

+118
-74
lines changed

7 files changed

+118
-74
lines changed

‎architecture/architecture.adoc

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
//
33
// * n/a
44

5-
ifdef::context[:parent-context: {context}]
65
[id='architecture']
76
= {product-title} Architecture
87
include::modules/common-attributes.adoc[]
@@ -21,6 +20,8 @@ include::modules/architecture-overview.adoc[leveloffset=+1]
2120

2221
include::modules/installation-options.adoc[leveloffset=+2]
2322

23+
include::modules/update-service-overview.adoc[leveloffset=+2]
24+
2425
include::modules/node-management.adoc[leveloffset=+2]
2526

2627
include::modules/node-types.adoc[leveloffset=+2]
@@ -33,5 +34,13 @@ include::modules/security-overview.adoc[leveloffset=+2]
3334

3435
include::modules/machine-api-overview.adoc[leveloffset=+1]
3536

36-
ifdef::parent-context[:context: {parent-context}]
37-
ifndef::parent-context[:!context:]
37+
[[observability-architecture]]
38+
== Observability
39+
40+
[IMPORTANT]
41+
====
42+
This section of the assembly is a placeholder for the Observability section,
43+
which will explain how monitoring, alerting, grafana, logging, and telemetry fit together.
44+
====
45+
46+
include::modules/telemetry-service-overview.adoc[leveloffset=+2]

‎modules/architecture-overview.adoc

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,23 @@
55
[id='architecture-overview-{context}']
66
= Architecture overview
77

8-
Like {product-title} v3, {product-title} v4 is a layered system designed to
9-
expose underlying container images and Kubernetes concepts as accurately as
10-
possible, with a focus on easy composition of applications by a developer.
11-
For example, after your cluster is running, install Ruby, push code, and add
12-
MySQL to the app.
8+
With {product-title} v4, the core story remains unchanged: {product-title} offers
9+
your developers a set of tools to evolve their applications under operational oversight
10+
and using Kubernetes to provide application infrastructure. The key change to v4 is
11+
that the infrastructure and its management are flexible, automated, and self-managing.
1312

1413
A major difference between {product-title} v3 and v4 is that v4 uses Operators
1514
as both the fundamental unit of the product and an option for easily deploying
1615
and managing utilities that your apps use.
1716

18-
{product-title} has an Operator-based architecture of smaller, decoupled units
19-
that work together. It runs on top of a Kubernetes cluster, with data about the
20-
objects stored in etcd, a reliable clustered key-value store. Those services are
21-
broken down by function:
17+
{product-title} v4 runs on top of a Kubernetes cluster, with data about the
18+
objects stored in etcd, a reliable clustered key-value store. The cluster is
19+
enhanced with standard components that you need to run your cluster, including
20+
network, ingress, logging and monitoring, that run as Operators to increase the
21+
ease and automation of installation, scaling, and maintenance.
22+
23+
////
24+
The core services include:
2225
2326
* Operators, which run the core {product-title} services.
2427
* REST APIs, which expose each of the core objects:
@@ -28,15 +31,22 @@ applications.
2831
proxy connections.
2932
** Projects and users, which provide the space and means for communities to
3033
organize and manage their content together.
31-
** Builds and image streams] allow you to
34+
** Builds and image streams allow you to
3235
build working images and react to new images.
3336
** Deployments, which expand support for the software development and deployment
3437
lifecycle.
35-
** Routes, which announce your service to the world.
36-
** Templates, which allow you to simultaneously create many objects that are
37-
based on customized parameters.
38+
** Ingress and routes, which announce your service to the world.
3839
* Controllers, which read those REST APIs, apply changes to other objects, and
3940
report status or write back to the object.
41+
////
42+
43+
{product-title} offers a catalog of supporting application infrastructure that
44+
includes:
45+
46+
* Operators, which expose APIs that automate the complete component lifecycle
47+
and include components like databases
48+
* Service bindings, which consume services that run outside the cluster
49+
* Templates, which are simple instant examples
4050

4151
Users make calls to the REST API to change the state of the system. Controllers
4252
use the REST API to read the user's desired state and then try to bring the

‎modules/installation-options.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@ The fully-managed option offers full-stack automation to:
1919
* Manage control plane
2020
* Manage nodes
2121

22-
The bring your own infrastructure option, you have more responsibilities.
22+
With the bring your own infrastructure option, you have more responsibilities.
2323
You must provide the hosts and update RHEL on them. {product-title} provides:
2424

2525
* Managed control plane
2626
* Ansible to manage kubelet and runtime
2727

2828

29-
With both installation types, installation and upgrade both use a controller
29+
With both installation types, installation and upgrade both use an Operator
3030
that constantly reconciles component versions as if it were any other Kubernetes
3131
controller.

‎modules/node-types.adoc

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,22 @@
22
//
33
// * architecture/architecture.adoc
44

5-
[id='node-types-{context}']
6-
= Node types in {product-title}
5+
[id='node-roles-{context}']
6+
= Node roles in {product-title}
77

8-
{product-title} uses bootstrap, master, and worker nodes. The bootstrap node
9-
provides the initial configuration to clusters. Master nodes run the cluster
8+
{product-title} assigns nodes different roles. These roles define the function
9+
of the node within the cluster. The cluster contains standard definitions for
10+
standard role types, such as bootstrap, master, and worker.
11+
12+
A node with the bootstrap role
13+
provides the initial configuration to clusters and is used only during initial
14+
configuration.
15+
16+
Nodes with the master role run the cluster
1017
infrastructure and required components. Instead of being grouped into a `MachineSet`,
1118
they are a series of standalone machine API resources. Extra controls apply to
1219
master nodes to prevent you from deleting all master nodes and breaking your
13-
cluster. The worker nodes drive compute workloads. Each type of worker node is
20+
cluster.
21+
22+
Nodes with the worker role drive compute workloads. Each type of worker node is
1423
governed by a specific machine pool that autoscales them.

‎modules/operators-overview.adoc

Lines changed: 20 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -5,66 +5,35 @@
55
[id='operators-overview-{context}']
66
= Operators in {product-title}
77

8-
In {product-title} version 4.0, all cluster functions are divided into a series
9-
of component Operators.
8+
{product-title} v4 uses different classes of Operators to perform cluster
9+
operations and run services on the cluster for your applications to use.
1010

11-
Operators can manage other Operators within their component. This lends to a
12-
transparent model: a single Operator usually manages a single binary file.
13-
Operators also offer a more granual configuration experience. You configure each component by
14-
modifying its Operator instead of modifying a global configuration file.
11+
[id='-platform-operators-overview-{context}']
12+
== Platform Operators in {product-title}
1513

16-
In version 4.0, separate processes and images and pods run to drive the kubernetes
17-
API and pod managers. The control plane services run as static pods so they can
14+
In {product-title} version 4.0, all cluster functions are divided into a series
15+
of platform Operators. Platform operators manage a particular area of
16+
cluster functionality, such as cluster-wide application logging, management of
17+
the Kubernetes control plane, or the machine provisioning system.
18+
19+
Each Operator provides you with a simple API for determining cluster
20+
functionality. The Operator hides the details of managing the lifecycle of that
21+
component. Operators can manage a single component or tens of components, but
22+
the end goal is always to reduce operational burden by automating common actions.
23+
Operators also offer a more granular configuration experience. You configure each
24+
component by modifying the API that the Operator exposes instead of modifying a
25+
global configuration file.
26+
27+
In {product-title} v4, all control plane components are run and managed as
28+
applications on the infrastructure to ensure a uniform and consistent management
29+
experience. The control plane, services run as static pods so they can
1830
manage normal workloads or processes the same way that they manage disaster
1931
recovery. Aside from the core control plane components, other services run as
2032
normal pods on the cluster, managed by regular Kubernetes constructs. Unlike in the past
2133
where the `kubelet` could be running as containerized or non-containerized, the `kubelet`
2234
always runs as a `systemd` process.
2335

2436

25-
[id='cluster-version-operator-{context}']
26-
== The cluster version Operator
27-
28-
The cluster version Operator orchestrates all things.
29-
30-
{product-title} 4.0 introduces several new components that support the cluster
31-
version Operator, including Cincinnati and Telemetry.
32-
33-
Cincinnati is the hosted service that provides over the air updates to both
34-
{product-title} and RHCOS. It provides a graph, or diagram that contain
35-
_vertices_ and the _edges_ that connect them, of component Operators. The edges
36-
in the graph show which versions you can safely upgrade to. The cluster version
37-
Operator checks with Cincinnati and determines valid upgrades and upgrade paths
38-
based on current component versions and information in the graph. If you
39-
configure it to do so, Cincinnati sends the release artifacts that it needs to
40-
perform the upgrade to your image registry, and the cluster version Operator
41-
upgrades your cluster. By accepting automatic updates, you can automatically
42-
keep your cluster up to date with the most recent compatible components.
43-
44-
To allow Cincinnati to provide only compatible updates, a release verification
45-
pipeline exists to drive automation. Each release artifact is verified for
46-
compatibility with supported cloud platforms and system architectures as well
47-
as other component packages. After the pipeline confirms the suitability of a
48-
release, Cincinnati can apply the update to your cluster or notify you that it
49-
is available.
50-
51-
The interaction between the registry and the Cincinnati service is different during
52-
bootstrap and continuous update modes. When you bootstrap the initial
53-
infrastructure, the cluster version Operator finds
54-
the fully qualified image name for the shortname of the images that it needs to
55-
apply to the server during installation. It looks at the image stream that it needs
56-
to apply and renders it to disk. It calls bootkube and waits for a temporary minimal control
57-
plane to come up and load the cluster version Operator.
58-
59-
During continuous update mode, two controllers run. One continuously updates
60-
the payload manifests, applies them to the cluster, and outputs the status of
61-
the controlled rollout of the Operators, whether they are available, upgrading,
62-
or failed. The second controller constantly checks with to Cincinnati to
63-
determine if updates are available.
64-
65-
In a managed Red Hat environment, Telemetry is the component that provides
66-
metrics about cluster health and the success of updates.
67-
6837
[id='second-level-operators-{context}']
6938
== Second-level Operators in {product-title}
7039

‎modules/telemetry-service-overview.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * architecture/architecture.adoc
4+
5+
[id='telemetry-service-overview-{context}']
6+
= The Telemetry service
7+
8+
In a managed Red Hat environment, Telemetry is the component that provides
9+
metrics about cluster health and the success of updates.

‎modules/update-service-overview.adoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * architecture/architecture.adoc
4+
5+
[id='update-service-overview-{context}']
6+
== The {product-title} update service
7+
8+
The {product-title} update service is the hosted service that provides over the air updates to both
9+
{product-title} and RHCOS. It provides a graph, or diagram that contain
10+
_vertices_ and the _edges_ that connect them, of component Operators. The edges
11+
in the graph show which versions you can safely upgrade to. The cluster version
12+
Operator checks with the {product-title} update service and determines valid upgrades and upgrade paths
13+
based on current component versions and information in the graph. If you
14+
configure it to do so, the {product-title} update service sends the release artifacts that it needs to
15+
perform the upgrade to your image registry, and the cluster version Operator
16+
upgrades your cluster. By accepting automatic updates, you can automatically
17+
keep your cluster up to date with the most recent compatible components.
18+
19+
To allow the {product-title} update service to provide only compatible updates, a release verification
20+
pipeline exists to drive automation. Each release artifact is verified for
21+
compatibility with supported cloud platforms and system architectures as well
22+
as other component packages. After the pipeline confirms the suitability of a
23+
release, the {product-title} update service can apply the update to your cluster or notify you that it
24+
is available.
25+
26+
The interaction between the registry and the {product-title} update service is different during
27+
bootstrap and continuous update modes. When you bootstrap the initial
28+
infrastructure, the cluster version Operator finds
29+
the fully qualified image name for the shortname of the images that it needs to
30+
apply to the server during installation. It looks at the image stream that it needs
31+
to apply and renders it to disk. It calls bootkube and waits for a temporary minimal control
32+
plane to come up and load the cluster version Operator.
33+
34+
During continuous update mode, two controllers run. One continuously updates
35+
the payload manifests, applies them to the cluster, and outputs the status of
36+
the controlled rollout of the Operators, whether they are available, upgrading,
37+
or failed. The second controller constantly checks with to Cincinnati to
38+
determine if updates are available.

0 commit comments

Comments
 (0)