---
title: Getting Started
weight: 10
aliases: /federated-edge-observability/getting-started/
---

:toc:
:imagesdir: /images
:_content-type: ASSEMBLY
include::modules/comm-attributes.adoc[]

[id="deploying-fe-pattern"]
== Deploying the {fe-pattern}

.Prerequisites

* An OpenShift cluster
 ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console].
 ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*.
* A GitHub account and a token for it with repositories permissions, to read from and write to your forks.
* The Helm binary, see link:https://helm.sh/docs/intro/install/[Installing Helm]
For installation tool dependencies, see link:https://validatedpatterns.io/learn/quickstart/[Patterns quick start].

[id="preparing-for-deployment"]
== Preparing for deployment
.Procedure

. Fork the link:https://github.com/validatedpatterns-sandbox/federated-edge-observability[federated-edge-observability] repository on GitHub. You must fork the repository because your fork is updated as part of the GitOps and DevOps processes.

. Clone the forked copy of this repository.
+
[source,terminal]
----
$ git clone git@github.com:<your-username>/federated-edge-observability.git
----

. Go to your repository: Ensure you are in the root directory of your Git repository by using:
+
[source,terminal]
----
$ cd /path/to/your/repository
----

. Run the following command to set the upstream repository:
+
[source,terminal]
----
$ git remote add -f upstream git@github.com:validatedpatterns-sandbox/federated-edge-observability.git
----

. Verify the setup of your remote repositories by running the following command:
+
[source,terminal]
----
$ git remote -v
----
+
.Example output
+
[source,terminal]
----
origin	git@github.com:kquinn1204/federated-edge-observability.git (fetch)
origin	git@github.com:kquinn1204/federated-edge-observability.git (push)
upstream	git@github.com:validatedpatterns-sandbox/federated-edge-observability.git (fetch)
upstream	git@github.com:validatedpatterns-sandbox/federated-edge-observability.git (push)
----

. Make a local copy of secrets template outside of your repository to hold credentials for the pattern.
+
[WARNING]
====
Do not place this file in your repository, and do not commit or push it. This would risk pushing personal credentials to GitHub.
====
+
Run the following commands:
+
[source,terminal]
----
$ cp values-secret.yaml.template ~/values-secret.yaml
----

. Populate this file with secrets, or credentials, that are needed to deploy the pattern successfully:
+
[source,terminal]
----
$ vi ~/values-secret.yaml
----

.. Edit the `vm-ssh` section to include the username, private key, and public key. To ensure the seamless flow of the pattern, the value associated with the `privatekey` and `publickey` has been updated with `path`. For example: 
+
[source,yaml]
----
  - name: vm-ssh
    fields:
    - name: username
      value: 'cloud-user'
    - name: privatekey
      path: '/path/to/private-ssh-key'
    - name: publickey
      path: '/path/to/public-ssh-key'
----
+
Paste the path to your locally stored private and public keys. If you do not have a key pair, generate one using `ssh-keygen`.

.. Edit the `rhsm` section to include the Red Hat Subscription Management username and password. For example:
+
[source,yaml]
----
  - name: rhsm
    fields:
    - name: username
      value: 'username of user to register RHEL VMs'
    - name: password
      value: 'password of rhsm user in plaintext'
----
+
This is the username and password that you use to log in to link:https://catalog.redhat.com/[registry.redhat.io.].

.. Edit the `cloud-init` section to include the `userData` block to use with cloud-init. For example:
+
[source,yaml]
----
  - name: cloud-init
    fields:
    - name: userData
      value: |-
        #cloud-config
        user: 'cloud-user'
        password: 'cloud-user'
        chpasswd: { expire: False }
----

.. Edit the `aap-manifest` section to include the path to the downloaded manifest zip file that gives an entitlement to run Ansible Automation Platform. Create a subscription manifest by following the guidance at link:https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.4/html-single/red_hat_ansible_automation_platform_operations_guide/index#proc-create-subscription-allocation_obtain-manifest[Obtaining a manifest file]. For example add the following: 
+
[source,yaml]
----
  - name: aap-manifest
    fields:
    - name: 
      path: '~/Downloads/<manifest_filename>.zip'
      base64: true
----

.. Edit the `automation-hub-token` section to include the token generated at . Click the *Load token* link at link:https://console.redhat.com/ansible/automation-hub/token[Automation Hub Token] to generate a token. For example:
+
[source,yaml]
----
  - name: automation-hub-token
    fields:
    - name: token
      path: '/path/to/automation-hub-token'
----

.. Optionally: Edit the `agof-vault-file` section to use the following (you do not need additional secrets for this pattern):
+
[source,yaml]
----
  - name: agof-vault-file
    fields:
    - name: agof-vault-file
      value: '---'
      base64: true
----

.. Edit the `otel-cert` section to include the path to a pre-existing TLS key and certificate. Populate as shown below:
+
[source,yaml]
----
  - name: otel-cert
    fields:
    - name: tls.key
      path: '~/federated-edge-observability-otel-collector-edge-observability-stack.key'

    - name: tls.crt
      path: '~/federated-edge-observability-otel-collector-edge-observability-stack.crt'
----
+
Certificates for the OpenTelemetry collector infrastructure. `Snakeoil` that is, self-signed certificates are automatically generated by the `makefile` as follows by the `make snakeoil-certs` target, which is automatically run by `make install`.

. Create and switch to a new branch named my-branch, by running the following command:
+
[source,terminal]
----
$ git checkout -b my-branch
----

. Edit the `values-global.yaml` file to customize the deployment for your cluster. The defaults in `values-global.yaml` are designed to work in AWS. For example:
+
[source,terminal]
----
$ vi values-global.yaml
----

. Add the changes to the staging area by running the following command:
+
[source,terminal]
----
$ git add values-global.yaml
----

. Commit the changes by running the following command:
+
[source,terminal]
----
$ git commit -m "No updates"
----

. Push the changes to your forked repository:
+
[source,terminal]
----
$ git push origin my-branch
----

The preferred way to install this pattern is to use the script `./pattern.sh` script. 

[id="deploying-cluster-using-patternsh-file"]
== Deploying the cluster by using the pattern.sh file

To deploy the cluster by using the `pattern.sh` file, complete the following steps:

. Log in to your cluster by running the following this procedure:

.. Obtain an API token by visiting link:https://oauth-openshift.apps.<your-cluster>.<domain>/oauth/token/request[https://oauth-openshift.apps.<your-cluster>.<domain>/oauth/token/request].

.. Log in to the cluster by running the following command: 
+
[source,terminal]
----
$ $ oc login --token=<retrieved-token> --server=https://api.<your-cluster>.<domain>:6443
----
+
Alternatively log in by running the following command:
+
[source,terminal]
----
$ export KUBECONFIG=~/<path_to_kubeconfig>
----

. Deploy the pattern to your cluster. Run the following command:
+
[source,terminal]
----
$ ./pattern.sh make install
----

.Verification

. Verify that the Operators have been installed, in the OpenShift Container Platform web console, navigate to *Operators → Installed Operators* page.
+
.federated-edge-observability-operators
image::/images/federated-edge-observability/FEO-operators.png[federated-edge-observability-operators,title="Federated Edge Observability Operators"]

. Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. 
+
.federated-edge-observability-applications
image::/images/federated-edge-observability/FEO-applications.png[federated-edge-observability-applications,title="Federated Edge Observability Applications"]

As part of installing by using the script `pattern.sh` pattern, HashiCorp Vault is installed. Running `./pattern.sh make install` also calls the `load-secrets` makefile target. This `load-secrets` target looks for a YAML file describing the secrets to be loaded into vault and in case it cannot find one it will use the `values-secret.yaml.template` file in the git repository to try to generate random secrets.

For more information, see section on https://validatedpatterns.io/secrets/vault/[Vault].

. Under *Virtualization* > *VirtualMachines*, the virtual machines show as `Running`. Once they are in `Running` state the
Provisioning workflow will run on them, install the OpenTelemetry collector, and start reporting metrics to the Edge Observability Stack
in the hub cluster.
+
.federated-edge-observability-vms
image::/images/federated-edge-observability/FEO-vms.png[federated-edge-observability-vms,title="Federated Edge Observability Virtual Machines"]

. Log in to the Grafana dashboard in the nines menu under *Grafana Observability*. Log in username and password is `admin`. 
+
.federated-edge-observability-grafana
image::/images/federated-edge-observability/FEO-grafana.png[federated-edge-observability-grafana,title="Federated Edge Observability Graphs"]

. Under *Dashboards* select *OpenTelemetry Collector HostMetrics (Node Exporter)* should be receiving data and drawing graphs for each of the nodes:
+
.federated-edge-observability-grafana
image::/images/federated-edge-observability/FEO-grafana-plotted.png[federated-edge-observability-grafana,title="Federated Edge Observability displayed Graphs"]

See link:/federated-edge-observability/ansible-automation-platform/[AnsibleAutomation Platform] for more information on how this pattern uses the Ansible Automation Platform Operator for OpenShift.

== Infrastructure Elements of this Pattern

=== https://www.redhat.com/en/technologies/management/ansible[Ansible Automation Platform]

A fully functional installation of the Ansible Automation Platform operator is installed on your OpenShift cluster to configure and maintain the VMs for this demo. AAP maintains a dynamic inventory of kiosk machines and can configure a VM from template to fully functional kiosk in about 10 minutes.

=== OpenShift https://docs.openshift.com/container-platform/latest/virt/about_virt/about-virt.html[Virtualization]

OpenShift Virtualization is a Kubernetes-native way to run virtual machine workloads. It is used in this pattern to host VMs simulating an Edge environment; the chart that configures the VMs is designed to be flexible to allow easy customization to model different VM sizes, mixes, versions and profiles for future pattern development.

=== HashiCorp https://www.vaultproject.io/[Vault]

Vault is used as the authoritative source for the Kiosk ssh pubkey via the External Secrets Operator. As part of this pattern HashiCorp Vault has been installed. Refer to the section on https://validatedpatterns.io/secrets/vault/[Vault].