== OpenShift

OpenShift is a Kubernetes-based platform for running containers. The
upstream project, https://www.openshift.org/[OpenShift Origin], is what
Red Hat bases the https://www.openshift.com/[OpenShift Container
Platform] product on. Fedora runs OpenShift Container Platform rather
than OpenShift Origin.

=== Getting Started

If you've never used OpenShift before a good place to start is with
https://www.openshift.org/minishift/[MiniShift], which deploys OpenShift
Origin in a virtual machine.

See the following for some: xref:openshift_bestpractices.adoc[Openshift Best Practices]

=== OpenShift in Fedora Infrastructure

Fedora has two OpenShift deployments:
https://console-openshift-console.apps.ocp.stg.fedoraproject.org/[Staging OpenShift] and
https://console-openshift-console.apps.ocp.fedoraproject.org/[Production OpenShift]. In addition to
being the staging deployment of OpenShift itself, the staging deployment
is intended to be a place for developers to deploy the staging version
of their applications.

Some features of OpenShift are not functional in Fedora's deployment,
mainly due to the lack of HTTP/2 support (at the time of this writing).
Additionally, users are not allowed to alter configuration, roll out new
deployments, run builds, etc. in the web UI or CLI.

==== Web User Interface

Some of the web user interface is currently non-functional since it
requires HTTP/2. The rest is locked down to be read-only, making it of
limited usefulness.

==== Command-line Interface

Although the CLI is also locked down to be read only, it is possible to
view logs and request debugging containers from os-control01 or your local machine. For
example, to view the logs of a deployment in staging:

....
$ ssh os-control01.iad2.fedoraproject.org
$ oc login api.ocp.fedoraproject.org:6443
You must obtain an API token by visiting https://oauth-openshift.apps.ocp.fedoraproject.org/oauth/token/request

$ oc login api.ocp.fedoraproject.org:6443 --token=<Your token here>
$ oc get pods
librariesio2fedmsg-28-bfj52          1/1       Running     522        28d
$ oc logs librariesio2fedmsg-28-bfj52
....

==== Deploying Your Application

Applications are deployed to OpenShift using
https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/openshift-apps[Ansible
playbooks]. You will need to create an
https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps[Ansible
Role] for your application. A role is made up of several YAML files that
define OpenShift objects.
To create these YAML objects you have two options:

[arabic]
. Copy and paste an existing role and do your best to rewrite all the
files to work for your application. You will likely make mistakes which
you won't find until you run the playbook and when you do learn that
your configuration is invalid, it won't be clear where you messed up.
. Set up your own deployment of OpenShift where you can click through
the web UI to create your application (and occasionally use the built-in
text editor when the UI doesn't have buttons for a feature you need).
Once you've done that, you can export all the configuration files and
drop them into the infra ansible repository. They will be "messy" with
lots of additional data OpenShift adds for you (including old revisions
of the configuration).

Both approaches have their downsides. #1 has a very long feedback cycle
as you edit the file, commit it to the infra repository, and then run
the playbook. #2 generates most of the configuration, but will produce
crufty files. Additionally, you will likely not have your OpenShift
deployment set up the same way Fedora does so you still may produce
configurations that won't work.

You will likely need (at a minimum) the following objects:

* A
https://docs.openshift.com/container-platform/4.15/cicd/builds/understanding-buildconfigs.html[BuildConfig]
- This defines how your container is built.
* An
https://docs.openshift.com/container-platform/4.15/openshift_images/image-streams-manage.html[ImageStream]
- This references a "stream" of container images and lets you trigger
deployments or image builds based on changes in a stream.
* A
https://docs.openshift.com/container-platform/4.15/applications/deployments/what-deployments-are.html[Deployment]
- This defines how your container is deployed (how many replicas, what
ports are available, etc)
- Note: DeploymentConfigs are deprecated, do not use them!
* A
https://docs.openshift.com/container-platform/4.15/applications/connecting_applications_to_services/getting-started-with-service-binding.html[Service]
- An internal load balancer that routes traffic to your pods.
* A
https://docs.openshift.com/container-platform/4.15/networking/routes/route-configuration.html[Route]
- This exposes a Service as a host name.
* Storage https://docs.openshift.com/container-platform/4.15/storage/index.html[Storage]
- On the Fedora Infra clusters in both staging and production, an automated storage provisioning system is in place. To access simply create a PVC:

----
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: PVCNAME-UPDATE
spec:
  volumeName: PVCNAME-VOL-UPDATE
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: 'ocs-storagecluster-cephfs'
  volumeMode: Filesystem
----


