---
title: Getting Started
weight: 10
aliases: /ansible-edge-gitops/getting-started/
---

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

[id="deploying-ansible-edge-gitops-pattern"]
== Deploying the Ansible Edge GitOps 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 with a personal access token that has repository read and write permissions.
* The Helm binary, for instructions, see link:https://helm.sh/docs/intro/install/[Installing Helm]
* Additional installation tool dependencies. For details, see link:https://validatedpatterns.io/learn/quickstart/[Patterns quick start].

It is desirable to have a cluster for deploying the GitOps management hub assets and a separate cluster(s) for the managed cluster(s).

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

. Fork the link:https://github.com/validatedpatterns/ansible-edge-gitops[ansible-edge-gitops] 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/ansible-edge-gitops.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/ansible-edge-gitops.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/ansible-edge-gitops.git (fetch)
origin	git@github.com:kquinn1204/ansible-edge-gitops.git (push)
upstream	git@github.com:validatedpatterns/ansible-edge-gitops.git (fetch)
upstream	git@github.com:validatedpatterns/ansible-edge-gitops.git (push)
----

. Make a local copy of secrets template outside of your repository to hold credentials for the pattern.
+
[WARNING]
====
Do not add, commit, or push this file to your repository. Doing so may expose 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 `kiosk-extra` section and populate as shown below:
+
[source,yaml]
----
  - name: kiosk-extra
    fields:
    # Default: '--privileged -e GATEWAY_ADMIN_PASSWORD=redhat'
    - name: container_extra_params
      value: '--privileged -e GATEWAY_ADMIN_PASSWORD=redhat'
----

.. 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 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
----

. 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 "any updates"
----

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

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

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

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

. Log in to your cluster by 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
----
+
Or 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. Navigate to *Operators → Installed Operators* page in the OpenShift Container Platform web console, 
+
.ansible-edge-gitops-operators
image::/images/ansible-edge-gitops/ansible-edge-ops.png[ansible-edge-gitops-operators,title="Ansible Edge GitOps Operators"]

. Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. 
+
.ansible-edge-gitops-operators-applications
image::/images/ansible-edge-gitops/ansible-edge-ops-applications.png[ansible-edge-gitops-operators-applications,title="Ansible Edge GitOps 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 the `Running` state the provisioning workflow runs on them, and installs Firefox, Kiosk mode, and the Ignition application on them:

. Select one of the VMs to see the details of the VM. The VMs are named `rhel8-kiosk-001` and `rhel8-kiosk-002`

.. Open the *Console* tab. Choose any of these options; this section assumes you chose `Ignition - Standard Edition`:

.. Read and accept the license agreement and click *Finish setup*.

.. Click *Start Gateway* to start the Ignition Gateway.

.. Log in to the application with the userid `admin` and the password you specified as the GATEWAY_ADMIN_PASSWORD in `container_extra_params` in your `values-secret.yaml` file.
+
.ansible-edge-gitops-vmconsole
image::/images/ansible-edge-gitops/aeg-openshift-vm-console-v1.png[ansible-edge-gitops-vmconsole,title="Ansible Edge GitOps VM Console"]

* See link:/ansible-edge-gitops/installation-details/[Installation Details] for more information about the installation steps.

* See link:/ansible-edge-gitops/ansible-automation-platform/[Ansible Automation Platform] for more information about how this pattern uses the
Ansible Automation Platform Operator for OpenShift.

* See link:/ansible-edge-gitops/openshift-virtualization/[OpenShift Virtualization] for more information about how this pattern uses OpenShift
Virtualization.

== 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].

== 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/4.16/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.

=== Inductive Automation https://inductiveautomation.com/[Ignition]

The goal of this pattern is to configure 2 VMs running Firefox in Kiosk mode displaying the demo version of the Ignition application running in
a podman container. Ignition is a popular tool in use with Oil and Gas companies; it is included as a real-world example and as an item to
spark imagination about what other applications could be installed and managed this way.

The container used for this pattern is the container https://hub.docker.com/r/inductiveautomation/ignition[image] published
by Inductive Automation.

=== 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].
