Cross-Functional Architecture And Tools For Cloud-Based Operating Models
This is a minimal starting point for developing an appliance using a custom controller that you can develop to encapsulate your own pre-existing programs inside of the Agile Cloud Manager’s interface. Local APIs are created on your DevBox using code in this example. The local APIs interact with Agile Cloud Manager to exchange information about state during each step in the runtime processes. After you get this example appliance running, you can begin to experiment with putting your own pre-existing code inside the example API code given in this example. You can then put your custom controllers inside any type of service in any system template alongside our built-in controllers, to build more sophisticated systems that leverage your existing code.
You will need a provisioned devbox in order to orchestrate this appliance using the Agile Cloud Manager. Either Windows or Linux.
For convenience, we have defined a simple process for spinning up a DevBox at this link .
If you already have a working DevBox that you created for one of the other appliance examples, you can reuse that DevBox for this example if you do the following things first:
Once you have created a DevBox, you can create a file in the DevBox named config.yaml in the $USER\acm\keys\starter directory and add the following precise contents to the file (REMOVE THE INDENTATION FROM EACH LINE. MAKE UP CUSTOM STRINGS ONLY FOR orgCustom. BUT KEEP EVERYTHING ELSE EXACTLY AS IT IS):
orgCustom: <random-5-character-string-withoutspaces>
networkName: some-network-name
sysName: some-system
vpcCIDR: 10.0.0.0/16
SSHLocation: 0.0.0.0/0
imageInstanceType: t2.small
imgNameCustom: cxstg5-ig4
availZone: us-west-2a
Make sure to keep all of the given values in config.yaml exactly as they are given above. For example, keep 10.0.0.0/16 for vpcCIDR, and so on. Only create one new string value orgCustom. Get the example app running with these values before trying to change any of the other values in config.yaml.
Create a file in the DevBox named keys.yaml at $USER\acm\keys\starter\keys.yaml
Your entire keys.yaml will look as follows:
KeyName: ACMKeyPair_xyz
For now, keep all the values in keys.yaml and config.yaml exactly as they are, with the exception of the orgCustom value. Later on, you can change all the values and add any new fields you need to because this is for a custom appliance that you will be free to develop any way you want. But start with these values the first time just to get it running the first time.
After you have confirmed that $USER\acm\keys\starter\keys.yaml and $USER\acm\keys\starter\config.yaml have been properly created, navigate the command line to any directory into which you want the Agile Cloud Manager to place resources for the given appliance.
Check the version by running the following command:
$ acm version
1.3
The version must be at least 1.3 to successfully run the Lake House example appliance. If you have a lower version installed, you will need to upgrade to the latest version, or at least to version 1.3.
Download and install all the requirements for the custom appliance by running the following CLI command:
acm setup on sourceRepo=https://github.com/AgileCloudInstitute/acm-demo-custom-api.git
After the setup command completes running, confirm that your current working directory directory contains an acmAdmin subdirectory and an acmConfig subdirectory in addition to subdirectories for the other repositories that are listed in the appliance’s setupConfig.yaml file. You should now be able to find setupConfig.yaml inside the acmConfig subdirectory now that the acm setup on sourceRepo=https://github.com/AgileCloudInstitute/acm-demo-custom-api.git command has completed running.
For example, on a Windows DevBox, you might run the dir command and see:
C:\path\to\mydirectory>dir
Volume in drive C is Windows
Volume Serial Number is 3E5E-9650
Directory of C:\p\a\acm_dl
10/25/2023 04:48 PM <DIR> .
10/23/2023 09:09 AM <DIR> ..
10/23/2023 09:35 AM <DIR> acm-system-templates
10/23/2023 09:34 AM <DIR> acmAdmin
10/23/2023 09:34 AM <DIR> acmConfig
10/23/2023 09:35 AM <DIR> <other-directories-corresponding-with-setupConfig.yaml-contents>
The acmAdmin and acmConfig subdirectories will be present for any acm working directory after setup is run. The acm-system-templates subdirectory is specific to this demo. The names of each subdirectory can be validated by examining the contents of the setupConfig.yaml file that you will find inside the acmConfig directory. Also, not that acmConfig contains the appliance-level code, while acmAdmin is where Agile Cloud Manager places files that it uses internally during runtime.
After validating setup, create the appliance by running:
acm appliance on
You can watch the appliance being created in the following two ways:
After the appliance has been created, you must destroy the appliance with the following command:
acm appliance off
If you encounter a problem, you can diagnose the problem by examining the logs. If you need help, create a ticket at the project website and someone will respond to help you in a timely manner.
Experiment with other CLI commands after the appliance has been destroyed. The other CLI commands will enable you to create and destroy individual components of the appliance.
The documentation for the CLI commands is at this link.
You can read about the language that defines the objects on which the CLI commands work at this second link.
And you can read about operating on the object model using the CLI at this third link.
Back up keys.yaml and config.yaml someplace safe so that you can re-use them later.
Run acm setup off if you wish.
Confirm that anything you created has now been deleted.
Make sure that there are no keys.yaml or config.yaml in your $USER\acm\keys\starter directory after you backed up those files to a safe location.
If you encounter any errors, or if you want to experiment, dig deeper, and potentially cleanup after running “acm appliance on” and “acm appliance off”, you can try reading the instructions at this link
Return to the list of example appliances at this link