keycloak-scim/docs/guides/operator/installation.adoc

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/options.adoc" as opts>
<#import "/templates/links.adoc" as links>
<#import "/templates/profile.adoc" as profile>

<@tmpl.guide
title="{project_name} Operator Installation"
priority=10
summary="How to install the {project_name} Operator on Kubernetes and OpenShift">

== Installing the {project_name} Operator
This {section} describes how to install the {project_name} Operator in a Kubernetes or OpenShift cluster.

=== Installing by using the Operator Lifecycle Manager

The recommended way to install the {project_name} Operator in Kubernetes environments is to use the Operator Lifecycle Manager (OLM).

==== Prerequisites
*  Make sure OLM is installed in your environment. For details, see https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/install/install.md#install-a-release[Installing OLM].

* Be sure that you have cluster-admin permission or an equivalent level of permissions granted by an administrator.

==== Using the OpenShift web console

The following procedure describes how to install the {project_name} Operator. However, for general instructions on installing Operators using OLM, see https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/[Install your operator with OLM]. In the default Catalog, the Keycloak Operator is named `keycloak-operator`. Make sure to use the `fast` channel to find the operator.

Perform this procedure on an OpenShift cluster.

. Open the OpenShift Container Platform web console.

. In the left column, click *Home*, *Operators*, *OperatorHub*.

. Search for "keycloak" on the search input box.
+
image::select-operator.jpeg["Select the {project_name} Operator in the UI"]

. Select the {project_name} Operator from the list of results.
. Follow the instructions on the screen.
+
Make sure you are installing from the *fast* channel:
+
image::configure-operator.png["Configure {project_name} Operator"]

You may select to either have the Operator watch the namespace where it is installed, or to watch a single namespace of your choosing.

<@profile.ifCommunity>
=== Installing by using kubectl without Operator Lifecycle Manager

You can install the Operator on a vanilla Kubernetes cluster by using `kubectl` commands:

. Install the CRDs by entering the following commands:
+
[source,bash,subs="attributes+"]
----
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
----

. Install the {project_name} Operator deployment by entering the following command:
+
[source,bash,subs="attributes+"]
----
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/{version}/kubernetes/kubernetes.yml
----

The Operator will watch the namespace where it is installed. You may optionally select a namespace with the `-n` option. 
</@profile.ifCommunity>

=== Installing Multiple Operators

It is currently not fully supported for the operator to watch multiple or all namespaces. In circumstances where you want to watch multiple namespaces, you can install multiple operators.

If you do this please be aware:

- all Operators share the CRDs (Custom Resource Definitions) as they are installed cluster wide.
- CRD revisions from newer Operator versions won't introduce breaking changes except for the eventual removal of fields that have been well deprecated. Thus newer CRDs are generally backward compatible.
- the CRDs installed last will be the ones in use. This applies to OLM installations as well where the Operator version, that is installed as the last, also installs and overrides the CRDs if they exists in the cluster already.
- older CRDs may not be forwards compatible with new fields used by newer operators. When using OLM it will check if your custom resources are compatible with the CRDs being installed, so the usage of new fields can prevent the simultaneous installation of older operator versions.
- fields introduced by newer CRDs will not be supported by older Operators. Older Operator will fail to handle CRs that use such new fields with an error deserializing an unrecognized field.

It is therefore recommended in a multiple Operator install scenario that you keep versions aligned as closely as possible to minimize the potential problems with different versions. 

</@tmpl.guide>