Skip to content

Latest commit

 

History

History
284 lines (182 loc) · 12.1 KB

custom-use-case.md

File metadata and controls

284 lines (182 loc) · 12.1 KB
Raw

Table Of Contents:


Introduction

In addition to use-cases provided natively by the ACE-Box, it is now possible to create custom use-cases. This capability allows using the ACE-Box as a platform to develop your own scenarios, demonstrations, trainings, etc.

In the next sections you can find all the needed information to develop your own custom use-case from scratch.


Get Started


Part A: Prepare your repository & spin up your ACE-Box

Let's create a custom use-case from scratch, in order to replicate the Basic Observability Demo use-case previously presented.

  1. First of all, create a new repository using the ext-template as a template.


  1. Give your repository a name and make it part of the dynatrace-ace space


  1. Clone your recently created repository locally. Later on, you could either make changes locally or within the ACE-Box VM instance.

    git clone https://github.com/dynatrace-ace/basic-dt-demo.git

  1. Now, follow the ACE-Box installation guide to spin up a VM and deploy the modules and configurations defined in the custom use-case template.
    Be sure to configure the use-case variable within the terraform.tfvars file to point to the custom use-case repository that we are about to develop:

    use_case = "https://<user>:<personal-access-token>@github.com/dynatrace-ace/basic-dt-demo.git"

    Note: you need to provide your github user and personal access token. Replace the placeholders above with your own values.


  1. Finish the installation guide and check the output of the terraform apply command with:

    terraform output

    Note: it should retrieve the IP & SSH key to access the VM that has been just created (ACE-Box)


  1. At this point, the framework has provisioned a VM on the selected Cloud Provider and it has automatically cloned our custom use-case repository (basic-dt-demo) under the /home/repos/repos/basic-dt-demo path.
    Next step is to go ahead implementing our custom use-case directly from the newly-created machine and, for for this reason, it's required to access the VM via SSH.

    Recommended: use an IDE such as Remote Development from Visual Studio for a more straight-forward and comfortable development experience.
    SSH config file example:

    Host <your-ace-box-ip>
HostName <your-ace-box-ip>
IdentityFile <path-to-the-ssh-key>
User ace

Part B: Build your custom use-case (Ansible)

At this stage, we have an empty ACE-Box (Linux VM) and we can start building our custom use-case on top of it. To do so, we are going to use Ansible and Ansible Roles to automate and simplify the process. Check out the Ansible Roles section for further details.

More in detail, we’ll build our custom use-case incrementally, modifying the my-use-case/tasks/main.yml configuration file step-by-step to instruct the Ansible engine on what to deploy to the ACE-Box VM. After each step, we let the engine parse the updated file and deploy the changes accordingly.


  1. After having successfully logged in into the ACE-Box VM, we are going to trigger a first run of the main.yml configuration file (which just contains a simple "Hello World" print at this stage) to get familiar with the ACE-Box and Ansible.

    To let the Ansible engine parse the configuration file and implement the instructions, run the following command on the terminal:

    ace enable https://github.com/dynatrace-ace/basic-dt-demo.git --local



    Note:

    The ace enable --local command does not clone the repository again, but it works with the local repository (which is at /home/repos/ace-box-ext-template) and enables the latest changes made during the use-case development. Furthermore, the command does not synchronize any local updates with the remote repository.

    The ace enable --local command is particularly useful during use-case development, as it allows to test and iterate on their changes without overwriting the work or interacting with the remote repository unnecessarily.


  1. Now, in order to replicate the Basic Observability Demo, we first need to deploy a k8s distribution. To do so, Read the k3s role documentation and add the following instructions to the main.yml file:

    - include_role:
    name: k3s

  1. Now that we declared what we want to deploy on the VM, we need to install k3s by running again the ansible main.yml leveraging on the same command we used at step 7:

    ace enable https://github.com/dynatrace-ace/basic-dt-demo.git --local

  1. Next step would be to add Dynatrace monitoring to our ACE-Box. Repeat step 8 & 9, but this time following the dt-operator role instructions:

      include_role:
    name: dt-operator

  1. Let's add a demo app. Repeat step 8 & 9, but this time following the app-easytrade role instructions:

    - include_role:
    name: app-easytrade

  1. Check the ingress defined for easytrade-app in order to access externally to the demo app:

    ace@ace-box-4c9z:~$ kubectl get ingress -A
NAMESPACE   NAME                CLASS    HOSTS                             ADDRESS       PORTS   AGE
easytrade   easytrade-ingress   <none>   easytrade.35.225.173.223.nip.io   10.128.0.20   80      113s

Part C: Closing Up

This is how your main.yml should look like at the end of Part B.

  1. Once you're happy with your changes, commit and push changes to the remote repository. Now you could safely destroy the ACE-Box following the instructions contained in the installation guide.
    Whenever you'll recreate it, all the resources and modules defined within the configuration files will get created automatically.

Get Pro (Coming soon...)

Let's extend our initial Basic Dynatrace Observability use-case, by using more OOTB & custom roles

  1. Add dashboard & gitlab

Coming soon...


  1. Create dt token & oauth token

Coming soon...


  1. Create DT configuration using Monaco, installing an App

Coming soon...


  1. Extending it, shell script, use variables (what default variables are avaiblable, extra.vars from terraform), custom role

Coming soon...

  1. What are and how to use Ansible variables

Coming soon...


Ansible Roles

Ansible is used for automatically setting up and deploying modules on top of the compute instance (VM) created by the ACE-Box framework via Terraform.

Ansible roles play a critical role in automating the setup and configuration of resources for custom use-cases. They are modular units that define specific tasks, such as installing software, configuring environments, or managing services. By leveraging these roles, ACE-Box simplifies the process of provisioning and configuring environments, making the creation and execution of use-cases more efficient.

Out-of-the-box Ansible Roles

Out-of-the-box Ansible roles are the roles that are natively provided by the ACE-Box framework, which cover common tasks and scenarios. Leveraging OOTB Ansible roles is recommended and ensures rapid and consistent deployments.

Referring to the Basic Obsevability Demo example, we have used several OOTB Ansible roles (k3s, dt-operator and app-easytrade) to deploy all the needed modules within the ACE-Box VM.

Check out the OOTB roles ReadMe for the complete list of Ansible roles natively provided by the ACE-Box framework.

All the information and the instructions to use an OOTB Ansible role are contained in the ReadMe file located within the folder where the role is defined.

For example, dt-operator ReadMe contains all the instructions to use and the dt-operator role.

Custom Ansible Roles

If a particular use-case requires actions beyond the OOTB roles, custom Ansible roles can be defined to meet those specific requirements. These custom roles can be integrated into the use-case's configuration, giving users flexibility while still maintaining a structured, automated approach.

Repository structure

In order for the ACE-Box to understand and properly deploy all the custom use-cases' modules using Ansible, it's mandatory that the custom use-case repository complies with the following folder structure:

roles/
  my-use-case/
    defaults/
      main.yml
    tasks/
      main.yml
    ...

More specifically, a folder named roles must to be available at the repository root, and it must include at least a my-use-case (literal, not renamed) sub-folder.

This roles folder, as well as all subfolders and files included in it, is synchronized with the ACE-Box's Ansible working directory. Upon a successful content sync, Ansible engine tries to use this my-use-case folder as an Ansible role and executes all the instructions specified within the configuration files.

Besides, it is possible to create other sub-folders to source additional custom Ansible roles:

roles/
  my-use-case/
  additional-custom-ansible-role/
  ...

For more information, please check out the official Ansible documentation.


Versioning

At one point, you probably want to create a hardened release of the custom repository you're working on. This is particularly important when a custom use-case is used as part of a hands-on training, etc.

A specific ref (version or branch) can be targeted by appending @my-version it to the use_case variable, e.g.:

use_case = "https://<user>:<token>@github.com/my-org/[email protected]"

Contribute

It is possible to extend the out-of-the-box use-cases by integrating the needed configuration files into the ACE-Box repository.


Troubleshoot

Known_hosts issue

If you get the following error lines while trying to access the ACE-Box server:

[10:04:38.930] Exec server for ssh-remote+35.225.173.223 failed: Error: Remote host key has changed, port forwarding is disabled
[10:04:38.930] Error opening exec server for ssh-remote+35.225.173.223: Error: Remote host key has changed, port forwarding is disabled

Check also in that piece of logs, where the known_hosts are defined, for example:

Offending ECDSA key in /Users/<user>/.ssh/known_hosts:6

And run the following command locally in order to remove the known_hosts:

rm /Users/<user>/.ssh/known_hosts

Then try to access again your VM