Skip to content

Adds upgrade paths for 3.7 #400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 9, 2022
Merged

Adds upgrade paths for 3.7 #400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions config_quay/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ include::modules/attributes.adoc[]


include::modules/config-intro.adoc[leveloffset=+1]
include::modules/config-updates-37.adoc[leveloffset=+2]
include::modules/config-updates-36.adoc[leveloffset=+2]
include::modules/config-file-intro.adoc[leveloffset=+2]
include::modules/config-file-location.adoc[leveloffset=+2]
Expand Down
16 changes: 10 additions & 6 deletions modules/con_schema.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Most {productname} configuration information is stored in the `config.yaml` file
using the browser-based config tool when {productname} is first deployed.


// TODO 36 Add link to standalone config guide
// TODO 36 Add link to standalone config guide
// https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/

The configuration options are described in the {productname} Configuration Guide.
Expand Down Expand Up @@ -164,7 +164,7 @@ azureStorage:
storage_path: /datastorage/registry
```

** **Google Cloud Storage**:
** **Google Cloud Storage**:
+
```
googleCloudStorage:
Expand All @@ -188,7 +188,7 @@ swiftStorage:
ca_cert_path: /conf/stack/swift.cert"
storage_path: /datastorage/registry
```

* **DEFAULT_SYSTEM_REJECT_QUOTA_BYTES** [string]: The quota size to apply to all organizations and users.
* **DISTRIBUTED_STORAGE_DEFAULT_LOCATIONS** [array]: The list of storage engine(s) (by ID in DISTRIBUTED_STORAGE_CONFIG) whose images should be fully replicated, by default, to all other storage engines.
** **Min Items**: None
** **Example**: `s3_us_east, s3_us_west`
Expand Down Expand Up @@ -254,10 +254,14 @@ swiftStorage:
** **Example**: `True`
* **FEATURE_PERMANENT_SESSIONS** [boolean]: Whether sessions are permanent. Defaults to True.
** **Example**: `True`
* **FEATURE_PROXY_CACHE** [boolean]: Whether to enable proxy caching for Red Hat Quay.
** **Example**: `True`
* **FEATURE_PROXY_STORAGE** [boolean]: Whether to proxy all direct download URLs in storage via the registry nginx. Defaults to False.
** **Example**: `False`
* **FEATURE_PUBLIC_CATALOG** [boolean]: If set to true, the `_catalog` endpoint returns public repositories. Otherwise, only private repositories can be returned. Defaults to False.
** **Example**: `False`
* **FEATURE_QUOTA_MANAGEMENT** [boolean]: If set to true, users have the ability to report storage consumption and to contain registry growth by establishing configured storage quota limits.
** **Example**: `True`
* **FEATURE_RATE_LIMITS** [boolean]: Whether to enable rate limits on API and registry endpoints. Defaults to False.
** **Example**: `False`
* **FEATURE_READER_BUILD_LOGS** [boolean]: If set to true, build logs may be read by those with read access to the repo, rather than only write access or admin access. Defaults to False.
Expand Down Expand Up @@ -368,7 +372,7 @@ swiftStorage:
* **LDAP_BASE_DN** [string]: The base DN for LDAP authentication.
* **LDAP_EMAIL_ATTR** [string]: The email attribute for LDAP authentication.
* **LDAP_UID_ATTR** [string]: The uid attribute for LDAP authentication.
* **LDAP_URI** [string]: The LDAP URI.
* **LDAP_URI** [string]: The LDAP URI.
* **LDAP_USER_FILTER** [string]: The user filter for LDAP authentication.
* **LDAP_USER_RDN** [array]: The user RDN for LDAP authentication.
* **LOGS_MODEL** [string]: Logs model for action logs.
Expand Down Expand Up @@ -439,7 +443,7 @@ swiftStorage:
* **MAXIMUM_LAYER_SIZE** [string]: Maximum allowed size of an image layer. Defaults to 20G.
** **Pattern**: ``^[0-9]+(G|M)$``
** **Example**: `100G`
* **PREFERRED_URL_SCHEME** [string]: The URL scheme to use when hitting
* **PREFERRED_URL_SCHEME** [string]: The URL scheme to use when hitting
{productname}. If {productname} is behind SSL *at all*, this *must* be `https`
** **enum**: `http` or `https`
** **Example**: `https`
Expand Down Expand Up @@ -480,7 +484,7 @@ swiftStorage:
* **SECURITY_SCANNER_V4_ENDPOINT** [string]: The endpoint for the V4 security scanner.
** **Pattern**: ``^http(s)?://(.)+$``
** **Example**: `http://192.168.99.101:6060`
* **SECURITY_SCANNER_V4_PSK** [string]: The generated pre-shared key (PSK) for Clair.
* **SECURITY_SCANNER_V4_PSK** [string]: The generated pre-shared key (PSK) for Clair.
* **SERVER_HOSTNAME** [string] required: The URL at which {productname} is accessible, without the scheme.
** **Example**: `quay.io`
* **SESSION_COOKIE_SECURE** [boolean]: Whether the `secure` property should be set on session cookies. Defaults to False. Recommended to be True for all installations using SSL.
Expand Down
10 changes: 10 additions & 0 deletions modules/config-updates-37.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
[[config-updates-37]]
= Configuration updates for Quay 3.7

== New configuration fields

* **FEATURE_QUOTA_MANAGEMENT**: Quota management is now supported. With this feature, users have the ability to report storage consumption and to contain registry growth by establishing configured storage quota limits. For more information about quota management, see link:https://access.redhat.com//documentation/en-us/red_hat_quay/3.7/html-single/use_red_hat_quay#red-hat-quay-quota-management-and-enforcement[Red Hat Quay Quota management and enforcement].

* **DEFAULT_SYSTEM_REJECT_QUOTA_BYTES**: The quota size to apply to all organizations and users. For more information about quota management, see link:https://access.redhat.com//documentation/en-us/red_hat_quay/3.7/html-single/use_red_hat_quay#red-hat-quay-quota-management-and-enforcement[Red Hat Quay Quota management and enforcement].

* **FEATURE_PROXY_CACHE**: Using Red Hat Quay to proxy a remote organization is now supported. With this feature, {productname} will act as a proxy cache to circumvent pull-rate limitations from upstream registries. For more information about quota management, see link:https://access.redhat.com/documentation/en-us/red_hat_quay/3.7/html-single/use_red_hat_quay#quay-as-cache-proxy[Red Hat Quay as proxy cache for upstream registries].
76 changes: 61 additions & 15 deletions modules/operator-upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[[operator-upgrade]]
= Upgrading the Quay Operator Overview
= Upgrading the Quay Operator Overview

The Quay Operator follows a _synchronized versioning_ scheme, which means that each version of the Operator is tied to the version of Quay and the components that it manages. There is no field on the `QuayRegistry` custom resource which sets the version of Quay to deploy; the Operator only knows how to deploy a single version of all components. This scheme was chosen to ensure that all components work well together and to reduce the complexity of the Operator needing to know how to manage the lifecycles of many different versions of Quay on Kubernetes.

Expand All @@ -17,20 +17,28 @@ When the Quay Operator is installed via Operator Lifecycle Manager, it may be co

The standard approach for upgrading installed Operators on OpenShift is documented at link:https://docs.openshift.com/container-platform/4.7/operators/admin/olm-upgrading-operators.html[Upgrading installed Operators].

[NOTE]
====
In general, {productname} only supports upgrading from one minor version to the next, for example, 3.4 -> 3.5. However, for 3.6, multiple upgrade paths are supported:
In general, {productname} supports upgrades from a prior (N-1) minor version only. For example, upgrading directly from {productname} 3.0.5 to the latest version of 3.5 is not supported. Instead, users would have to upgrade as follows:

* 3.3.z -> 3.6
* 3.4.z -> 3.6
* 3.5.z -> 3.6
====
. 3.0.5 -> 3.1.3
. 3.1.3 -> 3.2.2
. 3.2.2 -> 3.3.4
. 3.3.4 -> 3.4.z
. 3.4.z -> 3.5.z

This is required to ensure that any necessary database migrations are done correctly and in the right order during the upgrade.

For users on standalone deployments of Quay wanting to upgrade to 3.6, see the link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/upgrade_red_hat_quay/index#standalone_upgrade[Standalone upgrade] guide.
In some cases, {productname} supports direct, single-step upgrades from prior (N-2, N-3) minor versions. This exception to the normal, prior minor version-only, upgrade simplifies the upgrade procedure for customers on older releases. The following upgrade paths are supported:

. 3.3.z -> 3.6.z
. 3.4.z -> 3.6.z
. 3.4.z -> 3.7.z
. 3.5.z -> 3.7.z

=== Upgrading Quay
To update Quay from one minor version to the next, for example, 3.4 -> 3.5, you need to change the update channel for the Quay Operator.
For users on standalone deployments of Quay wanting to upgrade to 3.6, see the link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/upgrade_red_hat_quay/index#standalone_upgrade[Standalone upgrade] guide.


=== Upgrading Quay
To update Quay from one minor version to the next, for example, 3.4 -> 3.5, you need to change the update channel for the Quay Operator.

For `z` stream upgrades, for example, 3.4.2 -> 3.4.3, updates are released in the major-minor channel that the user initially selected during install. The procedure to perform a `z` stream upgrade depends on the `approvalStrategy` as outlined above. If the approval strategy is set to `Automatic`, the Quay Operator will upgrade automatically to the newest `z` stream. This results in automatic, rolling Quay updates to newer `z` streams with little to no downtime. Otherwise, the update must be manually approved before installation can begin.

Expand All @@ -41,7 +49,7 @@ For `z` stream upgrades, for example, 3.4.2 -> 3.4.3, updates are released in th

* Previously, when running a 3.3.z version of {productname} with edge routing enabled, users were unable to upgrade to 3.4.z versions of {productname}. This has been resolved with the release of {productname} 3.6.

* When upgrading from 3.3.z to 3.6, if `tls.termination` is set to `none` in your {productname} 3.3.z deployment, it will change to HTTPS with TLS edge termination and use the default cluster wildcard certificate. For example:
* When upgrading from 3.3.z to 3.6, if `tls.termination` is set to `none` in your {productname} 3.3.z deployment, it will change to HTTPS with TLS edge termination and use the default cluster wildcard certificate. For example:
+
[source,yaml]
----
Expand Down Expand Up @@ -75,8 +83,8 @@ If possible, you should regenerate your TLS certificates with the correct hostna

The `GODEBUG=x509ignoreCN=0` flag enables the legacy behavior of treating the CommonName field on X.509 certificates as a host name when no SANs are present. However, this workaround is not recommended, as it will not persist across a redeployment.

==== Configuring Clair v4 when upgrading from 3.3.z or 3.4.z to 3.6 using the Quay Operator
To set up Clair v4 on a new {productname} deployment on OpenShift, it is highly recommended to use the Quay Operator. By default, the Quay Operator will install or upgrade a Clair deployment along with your {productname} deployment and configure Clair security scanning automatically.
==== Configuring Clair v4 when upgrading from 3.3.z or 3.4.z to 3.6 using the Quay Operator
To set up Clair v4 on a new {productname} deployment on OpenShift, it is highly recommended to use the Quay Operator. By default, the Quay Operator will install or upgrade a Clair deployment along with your {productname} deployment and configure Clair security scanning automatically.

For instructions on setting up Clair v4 on OpenShift, see link:https://access.redhat.com/documentation/en-us/red_hat_quay/{producty}/html-single/manage_red_hat_quay/index#clair-openshift[Setting Up Clair on a Red Hat Quay OpenShift deployment].

Expand Down Expand Up @@ -105,11 +113,49 @@ When the Quay Operator starts, it immediately looks for any `QuayRegistries` it
* If `status.currentVersion` equals the Operator version, reconcile as normal.
* If `status.currentVersion` does not equal the Operator version, check if it can be upgraded. If it can, perform upgrade tasks and set the `status.currentVersion` to the Operator's version once complete. If it cannot be upgraded, return an error and leave the `QuayRegistry` and its deployed Kubernetes objects alone.

== Enabling features in Quay 3.7

=== Quota management configuration

Quota management is now supported under the `FEATURE_QUOTA_MANAGEMENT` property and is turned off by default. To enable quota management, set the feature flag in your `config.yaml` to `true`:

[source,yaml]
----
FEATURE_QUOTA_MANAGEMENT: true
----

=== Using Red Hat Quay to proxy a remote organization configuration

Using Red Hat Quay to proxy a remote organization is now supported under the `FEATURE_PROXY_CACHE` property. To enable proxy cache, set the feature flag in your `confg.yaml` to `true`:

[source,yaml]
----
FEATURE_PROXY_CACHE: true
----

=== {productname} build enhancements

Builds can be run on virtualized platforms. Backwards compatibility to run previous build configurations are also available. To enable virtual builds, set the feature flag in your `config.yaml` to `true`:

[source,yaml]
----
FEATURE_BUILD_SUPPORT: true
----

=== Geo-replication using the {productname} Operator

Deployments of {productname} with geo-replication is now supported by Operator deployments. To enable geo-replication, set the feature flag in your `config.yaml` to `true`:

[source,yaml]
----
FEATURE_STORAGE_REPLICATION: true
----

== Enabling features in Quay 3.6

=== Console monitoring and alerting

The support for monitoring Quay 3.6 in the OpenShift console requires that the Operator is installed in all namespaces. If you previously installed the Operator in a specific namespace, delete the Operator itself and reinstall it for all namespaces once the upgrade has taken place.
The support for monitoring Quay 3.6 in the OpenShift console requires that the Operator is installed in all namespaces. If you previously installed the Operator in a specific namespace, delete the Operator itself and reinstall it for all namespaces once the upgrade has taken place.

=== OCI and Helm support

Expand Down
Loading