# Overview Sigma Config User Guide ## Program information Greetings! We're grateful for your interest in Sigma Config. Sigma Config centralizes your infrastructure and application configuration for build, deploy and run time needs. Get your Ops, Dev and Security teams on the same page and simplify and organize your config data. Sigma Config becomes your single record of "configuration truth" for all infrastructure, applications and pipelines. ## Get Started * [**Getting Started**](/getting-started) * [Account Setup](/org-management/account-setup) * [Add an Integration](/reference/knowledge-base/integrations) * [Add a Parameter](/configuration-management/parameters/parameter-management/managing-parameters) * [CLI Installation](/configuration-management/cli-and-api/cloudtruth-cli) * [Create an API Access Token](/org-management/access-control/access-tokens#creating-an-api-token) * [Create a Template](/configuration-management/using-basic-templates) * [Model your Environment](/configuration-management/environments) * [Model your Projects](/configuration-management/projects) * [Invite your Team](/org-management/access-control/user-directory) ## Get Support **Discord:** Join our dedicated support channel with this [link](https://discord.gg/eBZXm9Tzr7). **Email:** Send your request to . **In-App:** Request support via the in-app chat feature. **New Features:** Feel free to comment on our proposed [roadmap](/reference/roadmap). # Getting Started Using the Sigma Config Solution. Sigma Config is a centralized configuration management hub that allows you to share values across your organization's applications and environments. Parameters and secrets can be created and stored directly within Sigma, or referenced from external sources, such as AWS SSM, Secrets Manager and S3. Unique parameter and secret values can be set for specific environments such as development, staging and production. Get started by creating a Sigma Config account, create your first parameters and Install the CLI to start accessing parameters across environments! {% content-ref url="/pages/-MW4DiDU07cHbkp6rkf6" %} [Account Setup](/org-management/account-setup) {% endcontent-ref %} {% content-ref url="/pages/-MW4DiDaLTLxwhhejpT\_" %} [Parameters](/configuration-management/parameters) {% endcontent-ref %} {% content-ref url="/pages/-MVHwuUM2hs02FvT8kTi" %} [CloudTruth CLI](/configuration-management/cli-and-api/cloudtruth-cli) {% endcontent-ref %} ## **QuickStart Guide** ### **Create a CloudTruth account** Create your CloudTruth account by navigating to the portal at [https://app.cloudtruth.io](https://app.cloudtruth.io/) You can choose to create a new login with CloudTruth or use an existing social login with a GitHub, Google or Microsoft account. ![](/files/9CbV0yIKPS0Lkw0YBqrw) You will be taken to the CloudTruth application where you will create an Organization. This is your own private space for creating and managing configurations. ### Create an Organization Enter a name for your organization, accept the [terms of service](https://cloudtruth.com/terms-of-service/) and click "Begin Free Trial". Don't worry, you can edit your organization name later. ![](/files/VgOSg4gkIKs7fCU4iRjz) ### ### Create your first Parameters From the Dashboard click `Add Parameter or Secret` to create a new parameter in `MyFirstProject`. ![](/files/q4QttFFzOtaOTAyYZ1qe) Provide the key with a name and click `Create Parameter`. ![](/files/F3n1sRM5AyWuBQjWHa9O) Enter an Internal value for the parameter and click `Save`. ![](/files/lBbnDeCrYgAsvHjsZ0ee) Repeat this process to add additional parameters or secrets. ### Create an API Access token Open the CloudTruth API administration screen by clicking `API Access` in the left hand menu. ![](/files/5wVuRpTUgQZHSHyTLeSu) \ Click `Generate New Token`, provide a Token Name\*\*,\*\* [viewer permissions](/org-management/access-control/user-directory#role-permissions) and click `Generate Token`. ![](/files/-MfDP_Lg_terRX8mkYSj) {% hint style="warning" %} Copy your access token now and secure it in a safe place. The token is only available at initial creation and will need to be regenerated if it is lost. {% endhint %} ![](/files/XFsqK8eRgOPZkfmSKkPI) ### Access Parameters with CloudTruth Run Install the [CloudTruth CLI](/configuration-management/cli-and-api/cloudtruth-cli) for your distribution and set the API access token in your environment. {% tabs %} {% tab title="Shell Install" %} The shell installer supports Linux and Darwin distros and will install the latest version. ``` (curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh || wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh) | sudo sh ``` Login with the CLI to create and set your [API Access token](/org-management/access-control/access-tokens) ``` cloudtruth login ========================= Use a browser to generate a new API token from the "API Access" page (https://app.cloudtruth.io/organization/api). Open the "API Access" page? (Y/n) Y Enter the new "API key" here: "YOUR_API_KEY" ``` {% endtab %} {% endtabs %} The CloudTruth run command will passthrough parameters into your environment. You can now see the parameters you created in your CloudTruth organization. ``` cloudtruth --project MyFirstProject run --inherit none --command printenv ``` Use CloudTruth run to get the value for a specific parameter that is sourced to your environment. ``` cloudtruth --project MyFirstProject run --command 'echo $YOUR_PARAMETER_KEY' ``` # Architecture # Security Overview ### Philosophy Take every precaution to prevent a compromise and limit the blast radius: * A compromised customer account should not allow CloudTruth or other customers' data access. * A compromised CloudTruth account should not allow access to customer secrets. * No CloudTruth service shall ever have direct public network access. Access to any service must be via a load balancer. * Secrets must be encrypted at rest and in transit. * Limit the amount of code that has access to cleartext secrets. This includes third-party libraries. * CloudTruth employees should not have access to customer secrets in plaintext without customer approval. All secret access must be audited. ### Infrastructure Our multitenant infrastructure runs in AWS spread across 3 availability zones in the us-east-2 region. Our service is split into 2 ECS clusters, with strict security group configurations on each. We strongly follow the principle of least privilege on all security groups and IAM policies. The 2 clusters: 1. The main app: api, docs, and web service 2. Internal vault: CloudTruth's main vault, used to manage certificates and JWT validation All ECS clusters are in a private VPC, with the only public access being from the Application Load Balancers to the API, docs, and Web App endpoints. We also use a Bastion host for admin access. ### User Data #### Non-secret data Non-secret parameters and other non-secret data are stored in a multitenant Postgresql database hosted by AWS RDS. All queries are scoped by the organization id of the user performing the operation. The scoping is performed on the backend and is not dependent on the user's information. The organization id is fetched from the user's JWT, which is created and signed by Auth0. #### Secrets In addition to the guardrails provided for non-secret data, an additional level of encryption is used to store Secrets in our Postgresql database. The encryption keys for this come from a unique data key generated for each customer organization using AWS KMS (the Envelope Encryption Method). The capability for a customer to provide their own KMS keys is available for our Enterprise subscription level. Doing so grants an additional level of insurance by allowing customers to revoke our access to their KMS key, immediately removing our ability to decrypt their secrets without needing us in the loop. #### Data Locations CloudTruth offers several operating modes that control how customer data is stored. 1. Import into CloudTruth 1. In this mode, your config data is stored in a CloudTruth managed AWS RDS instance. 2. Integrate with an external parameter or secret store 1. In this mode, your config data remains in a location you control. This could be AWS Parameter Store, Secrets Manager, Azure Key Vault, HC Vault, or Git repos. 2. CloudTruth makes a "symlink" to the external location and passes the values through the platform encrypted. The customer ultimately enforces the security controls and grants CloudTruth access to the locations. ### Authentication We use Auth0 as our Authentication provider. They allow users to authenticate with a username/password or with various social identity providers, such as Google, Microsoft, GitHub, etc. It also means we never have access to user passwords - that is only ever known by Auth0 (when using username/password auth) or the identity provider (Google, Microsoft, GitHub, etc.) When a user logs into the system (via Auth0), we get a JSON Web Token (JWT) in return with the user's id and their organization membership. All operations in the system require the JWT and are restricted to the organization contained in the JWT. The only exceptions are access to documentation (no auth required) and API-key authentication. #### API keys API Keys provide a convenient mechanism for authenticating automation systems, such as scripts and CI/CD pipelines. Any user with owner or admin permissions can create an API key. The user cannot create an API key with permissions greater than their own permissions, but they can reduce the access of the API key. Behind the scenes, the system will exchange the API key for a JWT from Auth0. The JWT is then used in all other operations. We'll cover more about how this exchange happens in another post. ### Authorization We have 2 different authorization systems: 1. Org membership, determined by the JWT 2. Role-based access controls (RBAC) #### Org membership The org membership authorization is performed early in the lifecycle of the request. You'll notice that our APIs don't ask for an organization id in any calls because the organization id is part of the JWT. This makes it impossible to query for things outside your currently active org. This carries all the way down to secret access. #### Role-based Access Controls We have implemented 4 roles as described below: 1. Owner - the org owner(s). Full permissions in the account. 2. Admin - Full permissions to the account except for account management (subscription changes, org deletion, etc.) 3. Contributor - Full permissions on projects, environments, parameters, and secrets. Cannot perform system operations like account management, user management, add/remove integrations, or view audit logs. 4. Viewer - read-only access to parameters. ### Audit All operations are logged with the user who performed the operation and when it occurred. Some operations have more detail logged, such as whether a push integration was successful. This immutable log records all operations regardless of source (UI, CLI, or API). The audit log is available to owners and admins and can be exported in JSON format. ### Encryption We take advantage of AWS encryption services for all supported products. For example, all EBS volumes and all S3 buckets are encrypted. In addition, we also maintain a chain of certs and keys used for TLS encryption. Our internal Vault service rotates the certs and keys frequently and rolls out automatically. #### Network encryption All network communications are encrypted with TLS v1.2 or later. All certificates are verified. This includes all internal service-to-service communications. There are no exceptions. #### Data at rest All customer data is encrypted at rest. This includes our main Postgresql database, all assets stored in S3, and all node-local storage to EBS volumes. ### Availability Our multitenant infrastructure runs in the us-east-2 region, is redundant across 3 availability zones and is configured for autoscaling via Spot by NetApp. ### Backups We take regular, automated snapshots of our database and additional snapshots preceding any admin operation. ### Code Security Our repositories require SSO from our corporate identity provider to access our internal repositories. Our code is scanned for viruses and vulnerabilities on every build, a process baked into our build automation. We also use multiple static code analysis tools to ensure we adhere to best practices. We measure code coverage on all components and maintain a high level of coverage. We use dependabot to keep all of our dependencies up to date. ### Admin Access We have no "God" accounts, but we have admins with privileged access to various systems. Access is achieved via a bastion host, which is limited to a whitelist of IP addresses of our admins. We also require MFA for admins. This includes running any out-of-cycle deploy code. All privileged account access is audited using a combination of tools, notifications, and scheduled procedures. # Copilot CloudTruth Copilot uses AI to help you create and manage proven config patterns for all your services. ### Copilot helps you do the following: * Evaluate templates against well-architected frameworks, security assessments, and known configuration vulnerabilities. * Import your configuration data from JSON, YAML, HCL, TF\_Vars, INI, and any structured data format. * Automatically create templates from project parameters. * Fix template syntax and consistency issues. * Use prompts to create config variables and templates for any project. * Learn how to use CloudTruth. Copilot does not share your configuration data with outside parties. ### Using the Copilot Invoke the Copilot at any time using the Copilot header menu option. First-time users will see a blank screen and ready to accept your first prompt. Returning users will see previous threads.

Start a new prompt

1. Click + to start a new thread or open a previous conversation. The state is preserved. 2. Previous conversations are accessible in the left-hand menu. 3. Select a canned prompt. Canned prompts may require more context, which you can add in the message box. 4. Send Copilot a prompt, upload a file to take action, or ask Copilot a question. ### Sample Copilot conversation

Copilot Main Interface

Here's a sample Copilot conversation requesting the AI to generate a Terraform AWS EKS best practices configuration file. The Copilot creates all the standard parameters with descriptions, default values, and templates in various formats: variables.tf, TF\_Vars, or main.tf. # Account Setup ## Organization Management Create your CloudTruth account by navigating to the portal at You can choose to create a new login with CloudTruth or use an existing social login with a GitHub, Google or Microsoft account. ![](/files/omya3eOGQSlUKC9xCrN7) You will be taken to the CloudTruth application where you will create an Organization. This is your own private space for creating and managing configurations. #### Create an Organization Enter a name for your organization, accept the [terms of service](https://cloudtruth.com/terms-of-service/) and click "Begin Free Trial". Don't worry, you can edit your organization name later. ![](/files/0Ma42VVjjp8unM4aauij) ### Multiple Organizations You can be a member of multiple organizations by creating a new organization or being invited to an additional org. Organizations are managed from the user dropdown menu by selecting `Switch Organizations`. ![](/files/e700y7YBAtK4Z0P71Wdg) The switch organizations page allows you to change the active organization that you are managing or create additional organization that you are a member of. ![](/files/j3Hn4UbmkO7FyN4oD2uG) ### **Creating and Accessing Parameters** Now that your organization is setup create some parameters and access them with the CloudTruth CLI or one of our other integrations. {% content-ref url="/pages/-MW4DiDaLTLxwhhejpT\_" %} [Parameters](/configuration-management/parameters) {% endcontent-ref %} {% content-ref url="/pages/-MVHwuUM2hs02FvT8kTi" %} [CloudTruth CLI](/configuration-management/cli-and-api/cloudtruth-cli) {% endcontent-ref %} {% content-ref url="/pages/-MW4DiDlUDTmPkfXC1kA" %} [Integrations](/configuration-management/integrations) {% endcontent-ref %} # Access Control Manage your interactive users, API Tokens, and (with an appropriate subscription level) access control to projects and environments. # API Tokens Programmatic REST API access to your configuration data. A CloudTruth API Token can be used with the [CloudTruth CLI](/configuration-management/cli-and-api/cloudtruth-cli) and for authorization directly with the REST API. When you create an API Token, we create a Service Account automatically - this is a non-interactive User, but for purposes of access control it behaves just like a regular User. All of the actions performed with the API Token are entered into the Audit Log using this Service Account. ## Creating a Service Account and generating a token: Only Contributor and higher roles can create Service Accounts and generate tokens. Service account role selection is based on the role of the user creating the service account, i.e. Contributor can only create a Service Account with Contributor or a lower privilege role. See [Role Permissions](/org-management/access-control/user-directory#role-permissions) for more details. 1. From the left-hand navigation locate `Admin` -> `API Tokens`:
2. Click `+ Create Token`​ to open the `CREATE NEW API TOKEN` modal:
* TOKEN NAME - Typically the name of the service the Service Account's token will be used for * DESCRIPTION - Optionally, describe the token's usage * OWNER - Typically the User who created the Service Account or is actively using the token in their environment. Used mainly for auditing purposes. Admins and Owners can view and manage all tokens regardless of ownership. * TOKEN PERMISSIONS - Set the Role the Service Account will have across the organization {% hint style="info" %} Service Account role assignments are organization-wide and treated the same as a [User Account](/org-management/access-control/user-directory) following the defined [organization role permissions](/org-management/access-control/user-directory#role-permissions). {% endhint %} 3. Click `Generate Token` to create the new Service Account and generate the ACCESS TOKEN. The Service Account along with the exposed and copyable token are now in the tokens list:
{% hint style="warning" %} The ability to copy the new token string is only available immediately after creating or generating a new token for the Service Account. Once the page has been navigated away from or refreshed the token will no longer visible or obtainable. {% endhint %} ## Managing Service Accounts (API Tokens) Service Accounts, for all intents and purposes, are treated the same as User Accounts without the ability to log in interactively. We provide easy mechanisms to update the Service Account's role, regenerate a token, or delete the Service Account. These options are found in the selection menu to the right of the token:
### Manage API Token 1. Select `Manage API Token` from the menu to open the `EDIT API TOKEN` modal:
2. Here you can modify the Description, change Owner, and modify the Role. 3. Click `Update` to save the changes ### Regenerate API Token 1. Select `Regenerate API Token` from the menu to open the `REGENERATE TOKEN` modal:
* Here we have two options: * Regenerate and immediately expire the previous token * Regenerate and set an expiration date and time for the previous token to expire #### Regenerate and expire immediately Clicking `Regenerate` will close the modal and display the new token as we did during Service Account creation. #### Regenerate and expire in the future If expiring the token at a later date and time is desired, as in cases where updating critical processes to use the new token may take some time, we can leave the previous token active by checking the box and entering a date and time:
2. After deciding which option is best, click the `Regenerate` button to create a new token for the service account. The token string will be displayed as before during Service Account creation. ### Deleting a Service Account 1. Selecting \`Delete API Token from the menu will prompt for confirmation:
2. Click `Yes, delete` to delete the Service Account along with any associated token(s) {% hint style="danger" %} This will immediately prevent access to CloudTruth via the Service Account's associated token(s) and is irreversible! Take care when deleting Service Accounts and make their tokens are no longer in use. {% endhint %} # Protecting Projects and Environments Business Subscription If you have a Business Subscription you can leverage Project and Environment Access Controls to restrict user access for organization contributors and viewers. Projects and Environments can be created by any user with write access, however they are created with access control disabled. If you do not have the appropriate subscription you will see an error message if you try to go into the access control pages: ![:(](/files/oqcu2dvJ30SO2NqSdVm8) ### Enabling Access Control Organization Owners and Administrators can enable Access Control on a Project or Environment and designate a Role for each user within it: ![Enabling Access Control](/files/2j9CfxOfL2wKzbaWBq9L) To enable Access Control, use the toggle control. This will make you the Owner of that Project or Environment. When Access Control is enabled, there must always be at least one Owner role in that Project or Environment. If a user does not have a Role assigned with Access Control enabled, they cannot see the Project or Environment. ![Managing Project Roles](/files/F2NMiDbxrgBgzNKzkGrd) {% hint style="info" %} Access Controls do not cascade through the project dependencies, therefore you will need to be precise with each project's access levels to ensure users can see all the projects in the dependency chain. {% endhint %} ### Disabling Access Control To disable Access Control, use the toggle control. Only an Organization Owner or Administrator can disable Access Control. {% hint style="warning" %} When you disable Access Control, all of the assigned Roles for the Project or Environment are dropped. If you want to enable Access Control again you will need to set all the roles again. {% endhint %} ### Organization Role Effects #### Organization Owners and Administrators As an Organization Owner or Organization Administrator, you are not subject to Access Controls. You can freely access any Project or Environment. You are allowed to enable or disable Access Controls on Projects and Environments. #### Organization Contributors If Access Control is enabled on a Project or Environment, you may be assigned a Role. If you are a Project or Environment Owner, you can freely manage roles of others to grant or deny them access to the Project or Environment. If you are a Project or Environment Administrator, you can manage roles of others up to being a peer Administrator within the Project or Environment, but you cannot modify the roles of Owners. If you are a Project or Environment Contributor, you can make changes within the Project or Environment but you cannot manage access of other users within the Project or Environment. If you are a Project or Environment Viewer, you can see content but are not allowed to make any changes within the Project or Environment. #### Organization Viewers Being an Organization Viewer means you have read-only access to the entire organization. The only Role that can be assigned to an Organization Viewer within a Project or Environment with Access Control enabled is that of a Viewer. # Users The User Directory allows for the invitation of additional interactive users and their roles to the organization. Only organization owners and admins can invite additional users. It is recommended to have at least two users assigned the Owner role in case either user needs to leave or be removed from the organization. {% hint style="info" %} Only an organization Owner may invite other users as Owners. Organization Admins are allowed to invite other users and set their roles to Admins, but not Owners. {% endhint %} The Users page is located in the Admin section of the left-hand navigation bar under Access Control:
## Inviting a new user 1. Click the `+ Create Users` button at the top of the page to open the `Invite team members` page:
2. Enter as many users as needed via a comma-delimited list, then click `Set User Roles`:
3. Here we set the user(s) role(s) as desired:
{% hint style="info" %} There is also the option to `REMOVE` an invitation from this page in case there is an unintentional e-mail address added. This avoids the need to cancel and start over {% endhint %}
4. Once the Roles are set as desired, click the `Set User Roles` button to send the invitations. 5. The Users list will now have the invitations listed:
6. If for any reason the invitation needs managed, we provide the options to either resend the invitation or delete it via the selection menu to the right of the invitation:
After the recipient accepts an invitation, the new user will appear in the Users list, and the invitation entry will no longer be present. ## Changing a user's role If for any reason a user's role needs to change it can be updated via the selection menu to the right of the user, by selecting `Change Role` which will open the `EDIT USER` modal:
Change the role as needed, then click `Update` for the change to take effect. {% hint style="warning" %} Changing a user's role requires an Owner role account. {% endhint %} {% hint style="warning" %} If the currently logged-in user is the only Owner, the account CANNOT be downgraded. If it must be re-assigned to a lower role, another user must be assigned the Owner role. {% endhint %} ## Removing a user from the organization When a user no longer requires access to an organization, it can be removed via the selection menu to the right of the user, by selecting `Remove Access` which will open a confirmation modal, select `Yes, remove` to remove the user from the organization.
{% hint style="warning" %} Removing a user requires an Owner role account. {% endhint %} {% hint style="warning" %} If the user being removed is the only Owner assigned role, another user must be assigned the Owner role before the account can be removed. {% endhint %} ## Leaving an organization Only Admins and Owners can leave an organization. The selection menu and confirmation modal change slightly where `Remove Access` changes to `Leave Organization` when clicking the selection menu for the currently logged in Admin or Owner:
Clicking `Yes, leave` will remove the currently logged in user from the organization. {% hint style="warning" %} If the currently logged-in user is the only assigned Owner role, then another user must be assigned the Owner role first before an Owner can leave an organization.If the currently logged-in user is the only assigned Owner role, then another user must be assigned the Owner role first before an Owner can leave an organization.If the currently logged in user is the only assigned Owner role, then another user must be assigned the Owner role first, before an Owner can leave an organization. {% endhint %} ## Role Permissions Detailed breakdown of organization and configurations management user role permissions. ***There is a special role called "VIEWERNOSECRETS," which has the same permissions as VIEWER but cannot view project secrets.***
Organization PermissionsOwnerAdminContributorViewer
View list of users✔️✔️✔️✔️
Create personal API access tokens✔️✔️✔️
Create - Update - Delete 3rd-party integrations✔️✔️
Manage and invite users✔️✔️
View and Download audit logs✔️✔️
Update non owner roles and users✔️✔️
Update owner role and users✔️
Manage Account✔️
Configuration PermissionsOwnerAdminContributorViewer
Switch Projects✔️✔️✔️✔️
View Project Parameters✔️✔️✔️✔️
View Project Secrets✔️✔️✔️✔️
View Project Templates✔️✔️✔️✔️
Create - Update - Delete Environments✔️✔️✔️
Create - Update - Delete Projects✔️✔️✔️
Create - Update - Delete Project Parameters✔️✔️✔️
Create - Update - Delete Project Templates✔️✔️✔️
# Audit Log The Audit log allows you to filter various attributes and download logs that provide you details on specific users and their actions across CloudTruth configuration management objects. Organization users must be an [Owner or Admin](/org-management/access-control/user-directory) to access the Audit logs. ![](/files/-Mi8Q-1zgpRexAtqzFt4) # Projects A CloudTruth project allows you to isolate parameters and templates for specific use cases within your organization. Each CloudTruth Organization starts with a default project `MyFirstProject`. Here are a few general ideas on how to use projects: * A project should represent the component you are trying to configure. This is frequently 1:1 with a git repo. * The parameters/secrets/templates in a project can be thought of the configuration *interface* for a component. Sometimes it is worthwhile to segment out a project further to segregate data further, e.g. the parameters need for tooling, or pipelines vs. the app itself. Environments represent an implementation of the configuration interface by supplying the concrete values for that environment * Using a project hierarchy as a means to group similar components together to enable sharing/linking of data common to those components. Projects higher up in the hierarchy would thus not represent individual components but a common ancestor to house common configuration data. ## Creating Projects Click `Create Project` from the global context at the top of the page, or use the global Create dropdown to locate and select the `Create Project` item.
Provide the Project a name, and any other optional values then click `Create Project`.
* **PROJECT NAME** - Typically the name representing an application or service (required) * **PARAMETER NAME PATTERN** - A regular expression parameter names must match, e.g. `FOO_.*` will require every parameter name to start with: `FOO_` (optional) * **DESCRIPTION** - Further describe the project's purpose (optional) * **PARENT PROJECT** - Nest the new project under a higher-level project to inherit the parent project's parameters, see [Project Inheritance](#project-inheritance) below (optional) ## Editing Projects All projects accessible by a user are represented on the page via the Projects tree:
Clicking on a project's edit icon will open the EDIT PROJECT dialog.
From here you can edit the main attributes of a project. * **PROJECT NAME** - Typically the name representing an application or service (required) * **PARAMETER NAME PATTERN** - A regular expression parameter names must match, e.g. `FOO_.*` will require every parameter name to start with: `FOO_` (optional) * **DESCRIPTION** - Further describe the project's purpose (optional) ## Project Inheritance We provide the ability to inherit another project's parameters as part of a project inheritance tree. This allows you to define a base set of parameters for your applications and share them across all of your projects. Child projects also allow overriding parameters at a specific project and environment level giving you complete control over your app configuration. If a project's inheritance needs to change, the project can be manually moved to its new location via the Project Tree. Simply click and drag the project from its current location to the destination location. Projects can be moved to the top-level or to any child position:
{% hint style="warning" %} Be sure to understand the ramifications of moving a project as will change the project's dependencies {% endhint %} Moving a project will include a confirmation request to make sure the move was intended where the message varies depending on what type of move is being made, moving a top-level parent project to become a child project:
Also, moving a child project to another location will indicate the dependency removal:
## Copying a Project Copying a project will copy all parameters and templates associated with the source project. This can be quite useful, especially when you have several similar projects. A project template or "gold master" can be created and labeled as such to avoid any boilerplate between projects. Clicking the symbol will open the COPY PROJECT dialog.
If the project being copied has dependents, a similar dialog will be displayed adding the ability to copy the dependent projects (which will also copy every project's associated parameters):
* **PROJECT NAME** - Typically the name representing an application or service (required) * **DESCRIPTION** - Further describe the project's purpose (optional, the visible placeholder is the default) * **PARENT PROJECT** - Nest the new project under a higher-level project to inherit the parent project's parameters, see [Project Inheritance](#project-inheritance) above (optional) * COPY DEPENDENTS - Checking this option will copy the original project and any of its dependent projects to the new project. Currently we do not provide the ability to re-name any copied dependents. They will be created with the same name with a short hash appended, e.g. `MySecondProject-b30c3498` ## Deleting a Project {% hint style="danger" %} Deleting a project deletes all parameters and templates that exist within that project! {% endhint %} Clicking the symbol will present a confirmation dialog:
Clicking `Yes, delete` will remove the project along with any associated templates and parameters. # Parameters CloudTruth Parameters allows management of parameters from a central source. This enables reeling in complicated and scattered configuration sprawl. Here is a list of how to manage parameters and the additional features we provide beyond simply providing a centralized parameter storage solution. * Standard (non-secret) and Secret Parameters * [Internal](/configuration-management/parameters/parameter-management/managing-parameters) and [External](/configuration-management/parameters/parameter-management/external-values) Parameter Value types * [Comparison of Values](/configuration-management/parameters/compare-values) * [History of Values](/configuration-management/parameters/history-of-values) * [Validation of Values](/configuration-management/parameters/rules-and-type) * [Expiration of Values](/configuration-management/parameters/value-expiration) CloudTruth Parameters exist across all [Environments](/configuration-management/environments) in a project. Parameters are always scoped to the selected [Project](/configuration-management/projects). There are two parameter value types: | Parameter | Definition | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Internal](#adding-an-internal-parameter-value) | User-defined parameter and value where values can be static or dynamically reference other CloudTruth objects (project, environment, other parameters, etc.) | | [External](/configuration-management/parameters/parameter-management/external-values) | Automatic parameter and value retrieved from an external source using a CloudTruth [integration](/configuration-management/integrations/aws) | {% hint style="info" %} Once created, parameters cannot be converted between secret and standard parameter types. {% endhint %} # Sharing Config Data Understand this important concept to simplify your config. One of our [seven core principle](https://7factorconfig.org)s is to keep your config [DRY](https://7factorconfig.org/dry). CloudTruth provides flexible methods and workflows to share secrets, parameters and templates across projects and environments. ### Interpolation CloudTruth's powerful [Dynamic Value](/configuration-management/parameters/parameter-management/managing-parameters#dynamic-parameters) parameter type allows you to reference and interpolate other values and templates from any project. Benefits include: * Reference one parameter from another to build more complex values. * An example is a database hostname, port, and URL value. With interpolation, the value can be constructed with individual settings. So if the port number changes, the new value only needs to change in one location, and all the references will automatically inherit the new value. * Reference parameters from another project. * Cherry-pick parameters to be shared or inherit all the values. * Implicit values allow config data to adjust according to context, avoiding creating too many variants which become difficult to manage at scale. Use implicit values for: * Ephemeral environments * Topic branches ### Project Inheritance Share parameters and secrets across projects from a common base project. Project inheritance works with interpolation. Benefits include: * Most config data can be organized to share a default value across projects. You don't lose anything by sharing since values can always be overridden for exceptional cases. * Supports templates as well as parameters and secrets. ### Environment Inheritance Environment inheritance allows sharing of config data across environments without repeating values. It's a core concept for [DRY config](https://7factorconfig.org/dry). Benefits include: * Set sane default values that can be inherited or easily overridden. * Secret rotation is easier because the secret only has to be changed in one location and will be reflected in all referenced values. # Parameter Management Parameters can be created as either standard or secret. A standard parameter will be visible as plain text in the UI or in any output from our CLI and API. Standard parameters are typically used for configuration values. A secret parameter will be masked in any output and will require an extra step or additional flag to reveal the secret value. Standard parameter values can be populated via either Internal or External sources. Secret parameters are typically passwords, private certificates, or any other sensitive information where one needs to be explicit as to when the values can be visible or unencrypted. Secret parameter values can be populated via either Internal or External sources. Secret parameters are also stored with additional encryption in the CloudTruth application. {% hint style="warning" %} Once created, parameters cannot be converted between secret and the standard parameter types. {% endhint %} ## Creating a parameter 1. Using the global context at the top of the page, select `Create Parameter` from the Action menu to open the `CREATE NEW PARAMETER` dialog:
* **NAME** - The parameter name used to reference the parameter's value (required) * **DESCRIPTION** - Further describe the parameter's purpose (optional) * **SECRET PARAMETER** - Select to mask the parameter's value by default when referenced (optional) * [**RULES**](/configuration-management/parameters/rules-and-type) - Expand to access the available parameter validation types and parameter value validation rules (optional):
* **PARAMETER TYPE** - Set the type to ensure parameter values conform to a particular type (optional, default type is `string`) * **RULE TYPE & CONSTRAINT** - Optional constraints based on the selected **PARAMETER TYPE** (optional) * [**EXPIRES**](/configuration-management/parameters/value-expiration) - Check the box to access the available parameter value expiration details (optional):
* **EXPIRES IN** - Period in days for which a value expires. * **AUTO-GENERATE VALUE** - When a parameter is set to expire, regenerate the value based on selected options (optional). Check the box to access the available options:
{% hint style="info" %} If `AUTO-GENERATE VALUE` is unchecked, the value will not be modified at the end of the expiration period and will be labeled as expired in the UI {% endhint %} 2. Click `Create Parameter` after filling out the required fields to finish the parameter creation process. Upon parameter creation, the app will automatically navigate to the Parameter Details page and open the `ADD ENVIRONMENT VALUE` modal to be able to add the required value. ## Editing a parameter Parameter settings can be modified via the `EDIT PARAMETER` modal. These are the same settings the create parameter process has without the ability to change from standard to secret or vice versa. 1. Open the EDIT PARAMETER modal by navigating to either the parameter list or a parameter's detail page and clicking the drop down selector and choosing: `Edit Parameter Settings`.
2. Make any modifications and then click `Save` to save the new settings and close the modal. ## Deleting a parameter 1. Navigating to either the parameter list or a parameter's detail page and clicking the drop down selector and choosing: `Delete Parameter`.
2. Confirm deletion by clicking `Yes, delete` to complete the parameter delete process. # Internal Values {% hint style="info" %} ### Learn more about [sharing config data](/configuration-management/parameters/sharing-config-data), implicit values, and interpolation. {% endhint %} Internal values are the most flexible of the parameter types, they can be plain text or dynamic, or a secret. Once a parameter has been created, the value can be added immediately after parameter creation or at a later time. Internal values can be converted between plain text values and [dynamic values](/configuration-management/parameters/parameter-management/managing-parameters/dynamic-values) and they can also be switched to [external values](/configuration-management/parameters/parameter-management/external-values). {% hint style="info" %} If the `ADD ENVIRONMENT VALUE` modal is cancelled, the value will be `NULL`. We recommend to always create the `default` environment value for a parameter then override the value in any child environments as needed. {% endhint %} ## Creating internal values 1. After creating a parameter, the `ADD ENVIRONMENT VALUE` modal will be displayed:
* **ENVIRONMENT** - This will typically be the `default` environment, to select a different environment to create the parameter's value in, cancel the dialog, select the appropriate environment via the ENVIRONMENTS tree, then click `Edit Value` to reopen the `ADD ENVIRONMENT VALUE` dialog * **SOURCE** - Internal (default) or External. This will define whether the parameter's value is hosted by CloudTruth or retrieved from a supported provider via a CloudTruth Integration Connection (required) * **DYNAMIC** - Allows the parameter's value to reference other parameters and templates via Mustache templating (optional) * **ENVIRONMENT VALUE** - Either the internal, external or dynamically set parameter value. * **Password generator** - Embedded convenience utility to quickly generate a password to copy and paste for the parameter's environment value 2. Enter the value in the ENVIRONMENT VALUE textbox:
3. Click `Save` to save the value Once the value has been saved, the parameter's detail page will be displayed showing the new value in the `default` environment, where the other child environments will indicate the value is being inherited from the `default` environment:
Editing Deleting (removing) ## Dynamic Parameters Marking a Parameter value as Dynamic allows you to reference and interpolate other values and templates from the project. This parameter `evaluated_demo` contains a value with text `evaluated_memory_size:` that includes the value from a referenced project parameter `{{service.app.memory}}`. ![](/files/zqUb1KAXKrttEgw14Rlr) Clicking `Show Evaluated` displays the evaluated value for the referenced parameter. ![](/files/0jjg8AmWV7hwCDYhFska) {% hint style="info" %} Dynamic values cannot be secrets, but they CAN reference secrets. If you have a secret you'd like to use in a dynamic value, store it in a secret Parameter and reference it in your dynamic value. A dynamic value that references a secret becomes a secret implicitly. {% endhint %} ## Overriding Parameter Values Parameters are present in all of the [Environments](/configuration-management/environments#multiple-environments) in a project and by default are set to the value from the parent Environment. You can set a unique Parameter value for each Environment by overriding the value. Click on a Parameter from the Parameter Store list. ![](/files/1xq3hdQf3xPknZtELCt1) The Parameter details page is displayed. In this example we have three Environments (Production, Dev and Staging) under the default parent. Select the Environment where you would like to override the value and click `Edit Value`. ![](/files/FaGvYQOZyfQ3uDnM9eN8) The Edit Environment Value page is displayed, set the Parameter value for the selected Environment and click Save. ![](/files/SVWuy77bbN3pkszdoZrw) Now the Parameter details page shows the updated value for the selected Environment. The remaining Environments retain the default value. ![](/files/icWGE8fyNV5GZWmlstxI) ### Inline Value Edits Parameters can also be edited from the Parameters, Compare and History pages. On each page the ![](/files/GUNqmrRxekQLMWglT9L5) will allow you to directly edit the value for a specific environment or remove an override. The Compare page will allow you to edit values for each environment selected in the compare. ![](/files/nzmRQblBwCFWhml3sqel) ## Searching Parameters As your Parameter list grows you can use the search to find all parameters with a specific string within your project. ![](/files/o63ZRCkFSzwu9s1KhupH) From the Parameter Store page you can list all Parameter values for a specific Environment by selecting the Environment in the drop down box. Values that have overrides for the selected Environment are indicated in the `Value Source`. ![](/files/caUGpDsCCEadgVl1n2d7) ## Edit Parameter Settings Select the Parameter you want to edit from the Parameter Store page and click `Edit Parameter Settings` from the Parameter menu. ![](/files/yFgDrKfjvjYPqnnzBwIw) The Edit Parameter dialogue allows you to update the description, change whether the parameter is a secret and update or set rules. ![](/files/8CIVKE0M1f0Qom3UfGUb) ## Deleting Parameters Select the Parameter you want to edit from the Parameter Store page and click `Delete Parameter` from the Parameter menu. ![](/files/low0OORNbk1l9TWV4aY4) ## Template References The Parameter settings page will display the number of [Templates](/configuration-management/using-basic-templates) a given Parameter is referenced in. You can navigate to each Template from the `Template List` tab. Parameters that are referenced in a template are protected from deletion. ![](/files/cvlXrTaQRlDgLx85HIDy) # Dynamic Values The dynamic values option provides the ability to reference parameters (standard or secret), templates, or other CloudTruth objects (project, environment, template) within a company's organization and interpolate their values. Dynamic values are obtained by using the [mustache](https://mustache.github.io/) logic-less template syntax. {% hint style="info" %} Only non-secret parameters can contain Dynamic Values; however, they can reference parameters marked as secrets. {% endhint %} ## Creating a dynamic value 1. After creating a new standard parameter, the `ADD ENVIRONMENT VALUE` modal is displayed, where clicking the `DYNAMIC` option switches the `ENVIRONMENT VALUE` input into a code editor and adds the `Evaluate` button for previewing the dynamic value before saving:

DYNAMIC unchecked

DYNAMIC checked

2. Starting with two left-hand braces `{{`, the editor will automatically insert the two right-hand braces `}}`. Start typing `cloudtruth` to access the available automatic parameter options, we'll select `project` for this example:
3. Click `Evaluate` to display the actual value of the parameter (to revert back the the code editor, click `Show Raw`):
4. Once satisfied, click `Save` to save the dynamic value. {% hint style="info" %} More information regarding available automatic parameters is covered in our Templates documentation in the [Automatic Parameters](/configuration-management/using-basic-templates#automatic-parameters) section {% endhint %} ## Interpolation The ability to interpolate, or retrieve values from existing parameters, is a great way to automatically produce values for a given environment based on data within the environment. Here's a simple example: Say we want to programmatically build a site per environment within a project. Normally, we would need to add a domain parameter for each environment which is unique such as: * production.example-app.com Hard-coding these parameters and overriding the values in each environment is doable, but quickly becomes overhead and error prone when new environments are created. Interpolation gives us the ability to 'build' this value at retrieval time, every time. When new environments are added, the dynamic variable is inherited and produces the correct value when retrieved without the need to manually update the value. Here's how we might do this: 1. Create a new project parameter for the default environment with a dynamic value which references the project:
2. This will produce a domain with top-level-domain base for the project:
3. Next, let's create another project parameter for the default environment with a dynamic value which references the environment *and* the previously created project parameter:
4. This will produce the full-domain string in a per environment fashion for the project:
5. Going back to the project's parameter list, we can see how useful this is by evaluating the values (click `Show Evaluated`) then selecting different environments to see the value update to reflect the currently selected environment:

development environment

production environment

This is a simple example of how interpolation produces values automatically and accurately every time they are retrieved and evaluated. # External Values Referencing values from external integration sources. In addition to setting internal parameter values directly within CloudTruth, parameters can be created with external values referencing CloudTruth's external [integration sources](/configuration-management/integrations). External values can be used as [overrides](/configuration-management/parameters/parameter-management/managing-parameters) in any CloudTruth environment, and parameters can contain a mix of external and internal values. First, set up CloudTruth integrations from your desired source. | Integration | Source Setup | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Azure | [Azure Key Vault](/configuration-management/integrations/azure-key-vault) (AKV) | | AWS | [S3](/configuration-management/integrations/aws/s3) | | AWS | [Parameter Store](/configuration-management/integrations/aws/parameter-store-ssm) (SSM) | | AWS | [S](/configuration-management/integrations/aws/secrets-manager)[ecrets Manger](/configuration-management/integrations/aws/secrets-manager) | | GitHub | [Repositories](/configuration-management/integrations/github) | When creating or editing a parameter value, select the `External` value type. ![](/files/gtAzfxoOL6tAZSNfLUcC) You are now presented with an external value screen for setting integration source values. The *Location* window will display your configured integration sources. In the example below we have both an AWS and GitHub integration. ![](/files/AuZk0ZDl1vI3ucgPxMuf) Depending on the source integration you will set an external value by selecting a key or querying a file for a key stored in your integration source file. We use the [JMESPath query language](https://jmespath.org/). | **Integration** | **Source** | **External Selection** | **Type** | | --------------- | --------------------------------------------------------------------------------- | ---------------------- | -------------------------------- | | AWS | [S3](/configuration-management/integrations/aws/s3) | JMESPath Query | file | | AWS | [Parameter Store](/configuration-management/integrations/aws/parameter-store-ssm) | Key Selection | String; StringList; SecureString | | AWS | [Secrets Manger](/configuration-management/integrations/aws/secrets-manager) | Key Selection | AWS secrets | | GitHub | [Repositories](/configuration-management/integrations/github) | JMESPath Query | file | **Key Selection** This example uses SSM to select a key `TF_VAR_availability_zone_names` which sets the CloudTruth value to `["us-west-2a", "us-west-2b"]`. ![](/files/V2Tyq7zGKlUl6kERdpuU) #### **JMESPath File queries** For integrations like AWS S3 and GitHub we use a [JMESPath selector](https://jmespath.org/) to query for a specific key from a supported file type to reference the external value. The following file types are supported: * JSON * XML * YAML * dotenv * tfstate The following example uses a JMESpath selector `timeout` to set the externally referenced value of `500` from the JSON content in the integration into to our CloudTruth parameter. You can test your reference by clicking "See Value" in order to display the contents of the Referenced Value. If the JMESPath selector does not return a valid result, error details will be displayed. ![JMESPath with JSON](/files/-Mk8iHufPT6qM20-VlcJ) #### JMESPath with XML XML with or without node attributes can be searched with JMESPath, however the expression can be a bit tricky. Consider the following simple XML content: ``` Natural dean castiel ``` A JMESPath query for `Data.Super` would give you the value `Natural`. A JMESPath query for ``Data.Project.Parameter[?"@name"==`rowena`]."#text" | [0]`` would give you the value `castiel`. Let's break that down: 1. `Data.Project` inspects each "Project", creating an array. 2. ``Parameter[?"@name"==`rowena`]`` searches the array for a Parameter entry with a `name` attribute set to `rowena`. 3. `"#text"` extracts the textual content of that node. 4. `| [0]` takes the resulting array matches (from step 1), filtered by step 2 and returns the first one. Without this, the result is `['castiel']`. ### Secrets with External values When referencing values from AWS Secrets Manager or Secure Strings from SSM the CloudTruth parameter must be [marked as a secret](/configuration-management/parameters/parameter-management/managing-parameters#edit-parameter-settings) in order to reference the secret value. If the CloudTruth Parameter is not marked as a secret the values will be locked. Since AWS Secrets manager values are always secure, secrets manager is locked at the top level. ![](/files/-Mi8Pw8eOszQiDjlUGyn) AWS Parameter store will intelligently only lock Secure String values. ![](/files/-Mi8Q1UNCLNE6lXgZ7B9) ### Refreshing External Values Each time you use the integration explorer from the parameter edit panel, CloudTruth will read the content and store the value to satisfy configuration queries. You can also refresh all of the values CloudTruth is handling through an integration by visiting the Actions menu and selecting Import. Each integration has a mapped import action you can trigger from there to refresh all of the mapped external values for that integration. In the future we plan to offer ways to keep the values synchronized automatically by watching the integration for changes through events and updating the values. # Terraform Remote State Files Link CloudTruth external parameter values to Terraform Remote State Files within S3. One practical use of CloudTruth external values is the ability to automatically reference Terraform state outputs. These outputs are normally generated and stored by Terraform in a file named `terraform.tfstate.`HashiCorp provides the ability for [Terraform state files to be stored remotely](https://www.terraform.io/docs/language/state/remote.html). AWS S3 is a common choice for [backend](https://www.terraform.io/docs/language/settings/backends/index.html) remote storage, and is often considered a best practice, especially when working with multiple users that may depend upon Terraform state outputs for CI/CD. Once CloudTruth external parameters referencing state files have been created, any parameter access will fetch the the value directly from the latest Terraform state on-demand! This includes parameter references from within the [Template](/configuration-management/using-basic-templates) mechanism that enables you to generate configuration files per-environment as needed. ## Remote State with Terraform You may already have remote state stored in S3 which can be used directly with the[ CloudTruth AWS S3 Integration](/configuration-management/integrations/aws/s3) to assign state output as [external values](/configuration-management/parameters/parameter-management/external-values). This walkthrough shows you how to setup a basic S3 bucket and deploy an EC2 instance to us-west-2 with a Terraform remote state file backend in S3 and reference the output as an external CloudTruth parameter value. #### Deploy an S3 bucket with Terraform You can use an existing S3 bucket for your remote backend or deploy a new S3 bucket with a unique name. Create an `s3` directory, change into the directory and create a file to define the S3 infrastructure. ``` mkdir s3 cd s3 touch main.tf ``` Open `main.tf` , paste in the configuration below, save the file, and run `terraform init` and `terraform apply`. ``` provider "aws" { profile = "default" region = "us-west-2" } resource "random_pet" "petname" { length = 1 separator = "-" } resource "aws_s3_bucket" "demo" { bucket = "cloudtruth-s3-${random_pet.petname.id}" acl = "private" force_destroy = true } output "YOUR_UNIQUE_BUCKET_NAME" { value = aws_s3_bucket.demo.bucket } ``` {% hint style="info" %} Note the output name of your newly created S3 bucket to use in the terraform s3 backend configuration. {% endhint %} #### Deploy configuration to a Terraform S3 backend Create a `remote-state` directory, change into the directory and create a file to define the infrastructure. ``` mkdir remote-state cd remote-state touch main.tf ``` The following Terraform configuration specifies [S3 as the backend](https://www.terraform.io/docs/language/settings/backends/s3.html) for your state file. Open `main.tf` and paste in the configuration below. Provide the bucket with `YOUR_UNIQUE_BUCKET_NAME`, save the file, then run `terraform init` and `terraform apply`. The EC2 instance will be created in us-west-2. Terraform will place the state file in the specified S3 bucket path `demo/instance/terraform.tfstate` and provide [outputs](https://www.terraform.io/docs/language/values/outputs.html) for the instance `id` and `public ip`. ``` terraform { backend "s3" { bucket = "YOUR_UNIQUE_BUCKET_NAME" key = "demo/instance/terraform.tfstate" region = "us-west-2" } } provider "aws" { profile = "default" region = "us-west-2" } resource "aws_instance" "app_server" { ami = "ami-830c94e3" instance_type = "t2.micro" tags = { Name = "RemoteStateInstance" } } output "instance_id" { description = "ID of the EC2 instance" value = aws_instance.app_server.id } output "instance_public_ip" { description = "Public IP address of the EC2 instance" value = aws_instance.app_server.public_ip } ``` {% hint style="success" %} Now that you have a remote state file in S3 and have configured the [AWS S3 CloudTruth Integration, ](/configuration-management/integrations/aws/s3)you can set your `terraform.tfstate` outputs as CloudTruth [External Values](/configuration-management/parameters/parameter-management/external-values). {% endhint %} **Set state as an External Value** As an example, while editing the External value of a parameter navigate to the S3 bucket destination path `demo/instance/terraform.tfstate` in the S3 integration and use the JMESPATH selector `outputs.instance_id.value`. Hit save to set the value to the instance id output from the remote state file. ![](/files/-Mk8iIOXwHZMdLIib-PH) Don't forget to cleanup your deploy infrastructure by executing a `terraform destroy` in the `S3` and `remote-state` folders. ## Remote State with Terragrunt Terragrunt provides a [quick start](https://terragrunt.gruntwork.io/docs/getting-started/quick-start/#keep-your-provider-configuration-dry) on creating a DRY [remote\_state ](https://www.terraform.io/docs/language/state/remote.html)configuration for the [backend](https://www.terraform.io/docs/language/settings/backends/index.html). You can use Terragrunt generated remote state with the [CloudTruth AWS S3 Integration](/configuration-management/integrations/aws/s3) to assign state output as [external values](/configuration-management/parameters/parameter-management/external-values). ![](/files/2YoKY801e7Xsmqa29u5d) Following the Terragrunt quick start guide as an example we created the following folder structure which will configure an S3 bucket and deploy an instance with remote state using the deployed bucket. ``` # terragrunt-remote-state ├── stage │ ├── instance │ │ └── main.tf │ │ └── terragrunt.hcl │ └── terragrunt.hcl ``` The `backend` configuration is defined once in the root stage `terragrunt.hcl` file. It will create a dynamodb lock table called `my-lock-table` and an S3 backend. You can update the bucket config with a unique name to follow along. ``` # stage/terragrunt.hcl remote_state { backend = "s3" generate = { path = "backend.tf" if_exists = "overwrite_terragrunt" } config = { bucket = "YOUR_UNIQUE_BUCKET_NAME" key = "${path_relative_to_include()}/terraform.tfstate" region = "us-east-1" encrypt = true dynamodb_table = "my-lock-table" } } ``` The instance folder contains a `terragrunt.hcl` that contains the Terragrunt helper [`find_in_parent_folders()`](https://terragrunt.gruntwork.io/docs/reference/built-in-functions/#find_in_parent_folders) which will inherit the `remote_state` configuration from the root terragrunt.hcl file in the directory tree. ``` # stage/instance/terragrunt.hcl include { path = find_in_parent_folders() } ``` The instance folder also contains a `main.tf` that will configure an EC2 instance in us-east-1 with outputs for the instance\_id and public ip. ``` # stage/instance/main.tf provider "aws" { profile = "default" region = "us-east-1" } resource "aws_instance" "app_server" { ami = "ami-0aeeebd8d2ab47354" instance_type = "t2.micro" tags = { Name = "RemoteStateInstance" } } output "instance_id" { description = "ID of the EC2 instance" value = aws_instance.app_server.id } output "instance_public_ip" { description = "Public IP address of the EC2 instance" value = aws_instance.app_server.public_ip } ``` Now you can change directory to the instance folder and run `terragrunt apply`. ``` cd stage/instance terragrunt apply -auto-approve --terragrunt-non-interactive ``` {% hint style="success" %} Terragrunt creates an S3 bucket with your unique name and is a destination for the instance configuration terraform.tfstate file! Now that you have a remote state file in S3 and have configured the [AWS S3 CloudTruth Integration, ](/configuration-management/integrations/aws/s3)you can set your `terraform.tfstate` outputs as CloudTruth [External Values](/configuration-management/parameters/parameter-management/external-values). {% endhint %} **Set state as an External Value** while editing the external value of a parameter navigate to the Terragrunt created S3 bucket destination path `instance/terraform.tfstate` in the S3 integration and use the JMESPATH selector `outputs.instance_id.value`. Hit save to set the value to the instance id output from the remote state file. ![](/files/j0O6n9HkWReNwTt2jJR3) Don't forget to cleanup your deploy infrastructure by executing a `terragrunt destroy` in the `instance` folder. You will need to manually delete the Terragrunt created S3 bucket as the wrapper does not provide a way to delete generated backends. # Parameter Override By default, parameters created in a parent, or root project, are automatically inherited in any child projects along with the parent's environment values. CloudTruth provides the ability to override parameters in situations where the child project might require different environment values. This essentially blocks inheritance from the parent project as if the parameter were created at the child project. We discuss inheritance further in the [Parameter and Parameter Value Inheritance section](/configuration-management/parameters/parameter-and-parameter-value-inheritance). In container-based applications, we might start with a top-level 'common' project to hold parameters which apply to all or some number of services. If we wanted to make sure every service started with a certain number of container, we could create a root-level project parameter named `container_count` and set with a reasonable value. This would ensure that every service configuration is set with a default container count which in turn makes for a valid configuration. Of course not all services are created equal, so some services may need a container count which is larger or lower than the default. Parameter override gives us the flexibility to generate valid configurations by default, then tweak each service as needed where a majority of the services would use the default value. Here's a simple example of how this would work: ### Set a 'common' default value:

Parent project with default parameter value set

Child project inheriting the parent parameter and parameter value

### Any new projects created under the 'common' parent automatically inherits the parents parameters and their values:

Create a new project as a child of the 'common' project

Child project listed under parent

New child project indicating parameter is inherited from parent

## Overriding a Parameter: 1. Starting from parameter list in the child project (`api`), click the selector to the right of the parameter and choose `Override Parameter`, this will immediately open the `OVERRIDE PARAMETER` modal:

Inherited parameter selection menu

2. Here you can make any adjustments to the `RULES` or parameter `EXPIRES` options if needed:
3. Click Override Parameter, this will display the parameter detail page for the overridden parameter:
4. Notice this is the same as any other parameter with some details on where this parameter obtained the original value. Here we've adjusted the overridden parameter's default environment value:
5. At this point, it may make sense to adjust any environment values for this service. In most cases, the `development` environment may not need the adjustments required by the staging and production environments. This adjustment can be made by selecting the `development` environment in the `ENVIRONMENTS` tree, clicking `Edit Value`, then saving the new value. We'll discuss [Value Overrides](/configuration-management/parameters/parameter-management/environment-value-override) in the next section.

Parameter detail page showing overridden parameter

Although not as common as overriding environments, overriding a parameter in a child project can help shape the CloudTruth project tree to closely match the organizations app's and services. Keeping the configuration as DRY as possible by leaving us with sane defaults for the most reused parameters, then making adjustments as needed without disrupting others. ## Removing a Parameter Override Removing a parameter override can be accomplished from either the project's parameter list or from the parameter details page:

Parameter detail page showing overridden parameter

1. Click the selector to the right of the parameter and choose `Remove Parameter Override`:
2. A confirmation modal will appear, click `Yes, remove` to complete the override removal:
Removing an override will reset inheritance for the previously overridden parameter. It will now inherit all environment values and attributes from the parent project's instance of the parameter. # Environment Value Override Environment Value Override allows us to customize individual environment values to suit an organization's needs. Values are typically created within the default environment where the 'starter' environments supplied by CloudTruth (development, production, staging) automatically inherit their values from the default environment. This is very useful to help guarantee a typical default value for all application environments the configuration is applied to when read from CloudTruth. When values need to be different across environments, that's when value overriding is needed. For example, database secrets, API Keys, and container constraints are just a few values which may differ between environments. More details regading parameter and parameter value inheritance can be found in the [Parameter and Paramter Value Inheritance](/configuration-management/parameters/parameter-and-parameter-value-inheritance) section. {% hint style="info" %} In a simple CloudTruth project structure, using the `development` environment values for the `default` environment ensures that all new environments will be given reasonable set of configuration and secrets values when created. Environment value overrides are typically for non-development environments when the values differ or need to be used by a limited set of team members for security purposes. {% endhint %} ## Overriding an environment value Starting within a parameter's details page:

Example parameter details page

1. Select the appropriate environment from the `ENVIRONMENTS` tree:
2. Click the `Edit Value` button:
3. Make the change to the value, then click `Save`:
4. The `ENVIRONMENTS` tree will update to the new value along with the Environment Value in the details:
Now when the `production` environment is retrieved, the updated value will be returned. ## Removing an environment override When needed, an environment override can be easily removed and the value will revert to the parent environment's value. We'll start from the parameter's details page:

Example overridden parameter details page

1. Select the appropriate environment from the `ENVIRONMENTS` tree:
2. Click the `Edit Value` button, the difference here is the highlighted `Remove Environment Override` button visible on overridden environments:
3. Click the `Remove Environment Override` button to remove the override. The modal will close and a message regarding the removal of the override will be displayed. 4. The `ENVIRONMENTS` tree will update with the name of the environment the value is being inherited from, along with the parameter details reflecting the same:
# Parameter and Parameter Value Inheritance In simple terms Projects have Parameters and Environments have Parameter Values. These are important concepts to grasp as we describe CloudTruth's inheritance model. ## Project and Parameter inheritance Parameters are created at the project level where each project can have any number of child projects. The parameters created in any higher-level (parent) project will naturally be inherited by any lower-level projects (children). These inherited parameters will be references to the upper-level project parameters unless they are manually overridden. Inheritance is always in effect until a parameter's environment values have been explicitly set. Once an environment value has been set, it no longer inherits its value from the parent project or environment as these values are static until any environment overrides have been removed. ### Overriding Project Parameters Lower-level project parameters can be overridden in order to manipulate a parameter's environment values in a child project. Overriding a parent project's parameter explicitly attaches the parameter to the child project and exposes the ability to modify the parameter's environment values. ## Environment and Parameter Value Inheritance Once a project parameter has been overridden we can now manipulate the parameter's environment values. Initially, each environment's parameter value will be inherited from the parent project's parameter environment values:
In this instance, we modified each parent project's parameter environment value. This causes an implicit inheritance from the parent project's parameter for each environment. Selecting each environment will update the Value Source indicating the value's referenced source location. From here, we can now modify any environment value to suit our needs. Depending on the desired outcome, we can reset the inherited values to the default value or edit the environment values individually. ### Resetting all child environment values to a new 'default' value In a child project, we can 'reset' or override the inheritance by editing the parameter's default environment value. This will update any implicitly inherited values from the parent project's environment values for each child environment and inherit the new default value. However, this only applies to those environment values in the child project which have not explicitly modified. Those values will remain the same as they are not inherited from the parameter's default value:
In the image above, we've edited the `default` environment's value resetting each child environment to inherit from the `default` environment. Notice the ValueSource has now changed from indicating the value being inherited from the parent project to now inheriting from the child project's default environment. ### Editing individual values Selecting a non-default environment, then editing it's value will explicitly set the value for that environment and it will no longer inherit its value from the parent environment:
Here, we've modified and explicitly set the `development` environment's value, note how the other environments are still inheriting from the `default` environment. Any changes to the `default` environment's value will not affect the `development` environment's value. To return an environment's value back an inheriting state, we can remove the environment override by editing the environment's value and clicking the `Remove Environment Override` button. This will remove the overridden value where the environment will now reference its parent's environment value.
### Editing a parent parameter's name There may be an instance where a parent-level parameter may need be renamed. This is tricky where inheritance is concerned and comes with some items to consider: * If the parameter is overridden in a child project, the child project's parameter becomes a new parameter at the child project's level and remains unchanged as well as the child project's descendants. * Any child project's directly in the inheritance line will still reference the parent parameter with the new name. Here we have an edited parameter name in a top-level parent project (note the INHERITED FROM is empty):
This parameter was overridden in the child project, which now displays the original parameter's name along with a new inherited reference to the modified parent parameter:
The original parameter has been decoupled from the parent project effectively creating a new parameter within the child project. This new child project parameter has no default or other environment values at this point. To use this parameter, new values will need to be assigned. # Value Comparison Did that critical setting make it to production?!? With CloudTruth Compare you can identify, diagnose and set configuration values for your [projects ](/configuration-management/projects)across multiple [environments ](/configuration-management/environments)from a single page. ## Comparing values across environments You can access the compare page from your selected project by clicking `Compare`. The compare screen displays the initial selected environment and the parameter values for that environment. ![](/files/t0uOuSfTIuEMuzm2duNE) The environment selection provides you with a dropdown allowing you to select multiple environments to compare values across. In this example we are selecting all of our environments for value comparisons. ![](/files/rhd3gpQGSMtkfwj9LqSj) The table now displays values for your project parameters across your selected environments. From here you can audit the value differences between default, development, production and staging. If you discover a value that is not quite right, you can also modify values across environments directly from the compare page with the edit operationfor each individual value. ![](/files/dCdua2gH5tKU9SFx818K) # Value History A brief history of time. 🕝 With CloudTruth you can view historical changes to configuration parameter values for your [projects ](/configuration-management/projects)and [environments](/configuration-management/environments). This allows you to audit and rollback configuration changes that may not have been effective or caused unintended behaviors in your application. ## Retrieving previous parameter value versions You can access the history page from your selected project by clicking `History`. The history screen displays the selected environment and the current parameter values for that environment. ![](/files/-MlGyTYHso1AAVoTJmbf) ### History by Tag You can select an [environment tag](/configuration-management/environments#tagging) to compare the current projects parameters to and click Apply. ![](/files/-MlGyTdHDZOHSY84PJ55) The table now displays values for your project parameters for the current time compared to the parameter values at the selected tag. ![](/files/-MlGyTjqJT-jscb_qBzF) You can rollback current values directly from the history page with the edit operation![](/files/-Mi8Pw8j1tR-gbewtRX0)for each individual value. ### History by date You can now select a date and approximate time to compare the current projects parameters to\*\*.\*\* ![](/files/-MlGyTdLxSXY1JC8zKeZ) The table now displays values for your project parameters for the current time compared to the parameter values at a previous point in time. If you discover a value that is not quite right, you can modify current values directly from the history page with the edit operation![](/files/-Mi8Pw8j1tR-gbewtRX0)for each individual value. ![](/files/-MlGyTdK0w2n6zf_40qW) ### # Value Validation This, not that. Nobody enjoys typos, especially ones that make their way into production and cause outages. With CloudTruth you can set a series of rules and typing on your parameters to ensure they meet a specific criteria, or syntax, that meet specific intended values. ## Creating Parameter Rules Rules are set on the parameter itself within a selected project that provide validation of values across all of the parameters environments. The following are the current rules you can set on your parameters. | Parameter Type | Allowed Rules | | -------------- | ------------------------------------------------------------------- | | String |

Minimum Length

Maximum Length

Regular Expression

| | Integer |

Minimum

Maximum

| | Bool | Boolean Types | {% hint style="info" %} We provide a regular expression rule for strings to come up with whatever crafty regex you require. {% endhint %} The Type and Rules can be set during parameter creation or when editing a parameter.

Value typed is shorter than the minimum length

Value is longer than maximum allowed length

{% hint style="info" %} When adding rules to an existing parameter, CloudTruth will check across all environments to make sure the existing values conform to the new rule(s). If any of the values do *NOT* conform to the proposed rule change, the app will display the what and how the rule conflicts. Those conflicts will have to be remediated prior to setting the rule. {% endhint %}

Adding a rule to an existing parameter where an environment value does not match the rule

Error message when rule cannot be applied due to an existing value mismatch

The rule type and constraint settings are listed in the parameter's detail page for convenience.
# Value Expiration Parameter Value Expiration gives us the ability to either visually alert or automatically rotate a parameter's values via a user specified duration. This is useful when a company policy requires secrets to be rotated on a regular basis. Parameter Value Expiration can be set during creation or added to existing parameters. ## Setting a parameter to not change on expiration This example will show how to create an expiring parameter which does not automatically change the parameter's environment values. Visual indication only. 1. Start by creating a new parameter 2. Check the `EXPIRES` option 3. Set the `EXPIRES IN:` duration
4. Add the `ENVIRONMENT VALUE` in the `ADD ENVIRONMENT VALUE` modal, then click `Save` 5. Note the expiration duration is visible in the parameter's detail page:
6. Go back the Parameter List to see the visual indicator next to the parameter's value and hover over the hourglass to quickly view the remaining duration before the parameter expires:
{% hint style="info" %} The hourglass icon will change colors at different stages: * Black - expiration time is outside of 5 days * Yellow - expiration time is within 5 days and has not yet expired * Red - parameter value has expired {% endhint %} ## Setting a parameter to automatically rotate values on expiration 1. Start by creating a new parameter 2. Check the `EXPIRES` option 3. Set the `EXPIRES IN:` duration 4. Check the `AUTO-GENERATE VALUE:` option 5. Select and modify the options as needed. The `Generate Password` button is there as a convenience and will generate a copyable password-style string to be pasted into the `ADD ENVIRONMENT VALUE` modal displayed after clicking `Create Parameter` here:
CloudTruth will check periodically for expired parameters and take the appropriate action to generate a new password and restart the duration clock. # Environments and Tags ## Environments CloudTruth Environments allow us to model an organization's hierarchy and define parameter values specific to the current environment context. Each CloudTruth Organization starts with the following environment tree: * **default** (the root environment, cannot be deleted or renamed) * **development** * **production** * **staging** Parameters inherit values from branches in the Environment tree allowing you to have a common default value throughout the Organization while also granting fine grain control over those values where required. ### Creating an Environment 1. Select **Create Environment** from the global Project and Environment action menu at the top of the page to open the **CREATE NEW ENVIRONMENT** dialog:
* **ENVIRONMENT NAME** - Typically a name representing a real world environment (required) * **PARENT ENVIRONMENT** - Existing environment to nest the new environment under (required, defaults to the current globally selected environment) * **DESCRIPTION** - Further describe the environment's purpose (optional) 2. Fill out the form with the appropriate information:
3. Submit the form to create the `dev1` environment as a child of the `development` environment.
### Environment Hierarchy In the example above, we have created a single child environment under the development environment:
This process can be repeated for complex models allowing very distinct parameter customization at multiple levels of your organization:
### Copying an Environment 1. On the Environments page, select the source environment to copy in either the global environment selector at the top or in the environment tree, then select the Copy option from the selected environment's action menu:
* **ENVIRONMENT NAME** - Typically a name representing a real world environment (required) * **DESCRIPTION** - Further describe the environment's purpose (optional) * **COPY DEPENDENTS** - This option is only available if there are dependent environments to the environment being copied. 2. Enter the appropriate information and click `Next`:
3. After reviewing, click `Copy Environment` 4. This will copy the environment as a top-level environment under the `default` environment, along with any dependent environments (with the `COPY DEPENDENTS` option checked):
{% hint style="info" %} All copied environments will be placed under the `default` environment. {% endhint %} ### Deleting an Environment 1. On the Environments page, select the environment to delete in either the global environment selector at the top or in the environment tree, then select the Delete option from the selected environment's action menu:
2. Click `Yes, delete` on the confirmation dialog to complete the environment deletion process. {% hint style="info" %} You will not be allowed to delete the `default` environment or any parent environment containing children. {% endhint %} ## Tags Tagging allows you to create a snapshot of parameters and values in a selected environment to a specific point in time. You can then use the tag to retrieve values for your applications. Tags are applied for the chosen environment across all projects in your organization. To see a tag's parameters and values use the [history feature ](/configuration-management/parameters/history-of-values#history-by-tag)or the via [CLI](/configuration-management/cli-and-api/cloudtruth-cli). ### Creating a Tag Select `Environments` in the left-hand navigation menu:

Environments

Click the `+ Create Tag` button to open the **CREATE NEW TAG** dialog:
* TAG NAME - Use a descriptive name to reference the tag, i.e. (stable, current, nightly) * IMMUTABLE - Prevents the tag's properties from being edited or updated, the tag will always reflect the data state of the selected timestamp when the tag was created * ENVIRONMENT - Choose the Environment to which the new tag will be applied * DESCRIPTION - Further describe the tag's purpose * TIMESTAMP - Choose a date and time for the parameter values the tag will represent (defaults to current date and time). ### Editing a Tag You can edit the timestamp, description, or make a tag immutable by selecting `Edit Tag` from the environment tag's ACTIONS menu:
Editing the timestamp of a tag will allow you to set the time and date to the last known good configuration in a tag e.g. `stable`:
{% hint style="warning" %} Updating a tag will automatically initiate any associated push actions. {% endhint %} Setting the `IMMUTABLE` option is useful when you need to take a snapshot of parameter and parameter values in a known good state before making any updates to those parameters. Once a tag has been set to immutable, the timestamp can no longer be updated. This guarantees the parameter and parameter values from that date and time will always be available to fall back to if needed. Immutable tags can only be deleted. ### Deleting a Tag The environment tag's ACTIONS menu also allows you to delete your tags.
# Templates Use Templates to transform Parameter and Secret values into any format. Templates allow parameters and secrets to be transformed into semi-structured or unstructured data formats. Templates are scoped to projects only and do not require a particular environment. For added value, the [Liquid Template Language](https://shopify.github.io/liquid/) can be used to dynamically generate template bodies. Templates are useful for pulling in semi-structured data into an application via our [CloudTruth CLI](/configuration-management/cli-and-api/cloudtruth-cli), the [Kubernetes Kubetruth operator](/configuration-management/integrations/kubernetes), or one of our many [Integration options](/configuration-management/integrations) *** ## Creating a Template {% hint style="info" %} Here are some [sample templates](/configuration-management/using-basic-templates/sample-templates) for JSON, YAML, ConfigMaps, TFVars and dotenv. {% endhint %} {% hint style="info" %} Since templates are scoped to projects, be sure to select the target project where the template will be used via the global project selector {% endhint %} 1. Select **Create Template** from the global Project and Environment action menu at the top of the page to open the **CREATE NEW TEMPLATE** dialog:
* **TEMPLATE NAME** - The reference name of the template used for retrieval * **DESCRIPTION** - Further describe the template's purpose (optional) 2. Fill out the form with the appropriate information:
3. Submit the form to create the `json` template within the targeted project:
4. This will expose the template editor, from here we can edit, preview, and submit the template:
5. In this example, we are using a Liquid script to structure the parameters and their values into the JSON format (note the `Draft` status on the left next to the template's name) {% hint style="info" %} Along with Liquid, CloudTruth provides several helper methods to retrieve various CloudTruth Application values to enhance the templating experience. See the [Automatic Parameters](#automatic-parameters) section below for the available parameters and descriptions. {% endhint %}
6. At this point, clicking `Preview` will generate the template's output for the selected environment, which is `default`:
{% hint style="info" %} On Preview, if any of the referenced parameters where created as a secret parameter, the entire template body will be masked as a protective measure. Clicking `Show Secrets` will reveal the entire template body. {% endhint %} 7. Provided there were no errors in the template during preview, clicking `Submit` will save the template.
## Editing a Template Once a template has been submitted and saved, editing a template is as easy as clicking the `Edit Template` button and using the same process to edit, preview, and submit the changes as we did in the [Create](#creating-a-template) process above. ## Deleting a Template 1. To delete a template, click the action menu in the template detail view and select `Delete`:
2. Simply confirm and the template will deleted.
*** ## Automatic Parameters In addition to your parameters, CloudTruth adds several automatic parameters that can be referenced in templates:
cloudtruth.selfThe name of the current template.
cloudtruth.projectThe name of the current project.
cloudtruth.environmentThe name of the current environment.
cloudtruth.environment.childrenreturns a list of the current environment's children
cloudtruth.templates.<name>evaluates template <name> against the current environment and includes its contents in this template.
cloudtruth.parameters.<name>Another way to reference the parameter <name>.
cloudtruth.projects.<name>A reference to another project. See below for more on referencing parameters and templates in other projects.
## Parameter Attributes All parameters automatically include attributes to allow retrieving attributes of that parameter. For example, to see the ID of your current project, use `cloudtruth.project.id`. These attributes are derived from the API and match the meaning in the API. The full list of available attributes is: | Attribute | Applies To | Description | | ----------- | ------------------------------------------------------ | -------------------------------------------------- | | id | All objects | The ID of the object. | | name | All objects | The name of the object. | | description | All objects | The description of the object. | | parent | Environments | The parent Environment of the current Environment. | | depends\_on | Projects | Project that the specified project depends on. | | value | Parameters and Templates | The value of the object. | | secret | Parameters and Templates | If True, the object is a secret. | | type | Parameters and Templates (including `cloudtruth.self`) | The type of the object. | ## CloudTruth Filters In addition to the usual filters Liquid provides, CloudTruth adds a few new ones for you: | Custom Filter | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dns_safe` | Ensures the value is safe for use as a DNS name or Kubernetes resources name. | | `env_safe` | Ensures the value is safe for setting as shell environment variable. | | `key_safe` | Ensures the value is safe for use as a key inside the Kubernetes ConfigMap/Secret data hash. | | `indent: count` | Indents each line in the value by `count` spaces. | | `nindent: count` | Adds a leading newline, then indents each line in the value by `count` spaces. | | `parse_yaml` | Parses a YAML string into a structured representation. | | `to_yaml` | Converts an object to a YAML representation. | | `parse_json` | Parses a JSON string into a structured representation. | | `to_json` | Converts an object to a JSON representation. | | `encode64` | Base64 encodes a value. | | `decode64` | Base64 decodes a value. | | `sha256` | Takes the sha256 digest of a value. | | `merge: other` | Merges the `other` hash value into this one. | | `re_replace: pat, repl, flags` | Regular expression replaces pattern `pat` in the value with replacement `repl`, with optional `flags` "i" for ignore case, "m" for multiline and "x" for extended. | | `re_contains: pat, flags` | Returns a boolean indicating whether the pattern `pat` is found in the value, with optional `flags` as re\_replace. | | `names` | Given a dictionary of parameters (e.g. `cloudtruth.parameters`), return a list of parameter names. | | `values` | Given a dictionary of parameters, return a list of parameter values. Note that parameter attributes are still available to objects in this list. | ## Guidelines ### Circular references CloudTruth will prevent creating a circular reference between templates, for example: * Template A references template B * Template B references templates C * Template C references template A Should a template result in a circular reference, CloudTruth will display an error and display the erroring circular reference. ### Parameters with non-conventional names CloudTruth does not restrict parameter names, but Liquid follows the traditional identifier naming conventions: alphanumerics and underscores only. If the need to reference a parameter with non-conventional characters arises, use the following guidelines: e.g. Referencing a parameter with special characters: `{{ My.Non Traditional Parameter Name! }}` Needs to be: `{{ cloudtruth.parameters["My.Non Traditional Parameter Name!"] }}` {% hint style="info" %} This notation can be used for any reference, conventional or non-conventional, for example: `cloudtruth.parameters["conventional_template_name"]` {% endhint %} ### Parameters and Templates from Other Projects By default, all parameters and templates are referenced from the current project. However, referencing a parameter or template from another project requires referencing the targeted project the parameter or template is associated first: Parameter: `{{ cloudtruth.projects..parameters. }}` `Template:` `{{ cloudtruth.projects..templates. }}` ## Template History You can view the history of raw project templates in the history page. Selecting Templates will bring up a template list for your specified project. ![](/files/-MlGyTdGaYIfA1JncK-2) #### Template History by Tag You can select an [environment tag](/configuration-management/environments#tagging) to compare the project's current templates to and click Apply. ![](/files/-MlGyTjoEYdTZ1Rra6mw) The table now displays a dropdown to show any differences in the templates for the current time compared to the templates content at the selected tag. Selecting the dropdown will bring up a side-by-side view of the template with highlighted differences. ![](/files/z94C09mqozAedAE8v3eM) #### History by date You can select a date and approximate time to compare the project's current templates to and click Apply. ![](/files/HgvPwXgJBvtdqDh4hql8) The table now displays a dropdown to show any differences in the templates for the current time compared to the templates content at the selected time. Selecting the dropdown will bring up a side by side view of the template with highlighted differences. ![](/files/XytxSXu5ouCjE1pKmKN5) # Sample Templates ### Copy these samples into the CloudTruth Template editor {% hint style="info" %} The samples include the relevant CloudTruth CLI command to fetch the template and assume the CloudTruth API key has been exported to an environment variable. {% endhint %} #### JSON 
#
# Iterates through all parameters in the project
#
{
{%- for param in cloudtruth.parameters %}
  "{{param[0]}}": "{{param[1]}}"{%unless forloop.last%},{%endunless%}
{%- endfor %}
}
#
#
# Sample CloudTruth CLI command to fetch this template:
# Remove below after copying
#
# Assumes CloudTruth API key is exported to ENV variable
# 
cloudtruth --project {{cloudtruth.project}} template get "{{cloudtruth.self}}"
#### YAML {% code lineNumbers="true" %} ```liquid # # Iterates through all parameters in the project # {%- for param in cloudtruth.parameters -%} {{param[0]}}: {{param[1]}} {% endfor -%} } # # # Sample CloudTruth CLI command to fetch this template: # Remove below after copying # # Assumes CloudTruth API key is exported to ENV variable # cloudtruth --project {{cloudtruth.project}} template get "{{cloudtruth.self}}" ``` {% endcode %} #### ConfigMap {% code lineNumbers="true" %} ```liquid # # Sample ConfigMap template Kubetruth will fetch from the platform # {% assign params = cloudtruth.parameters | values | where: "secret", false -%} {% assign version = cloudtruth.parameters | sort | to_json | sha256 | slice: 0, 7 -%} {% if params.size > 0 -%} kind: ConfigMap metadata: name: "{{ cloudtruth.project }}" namespace: "{{ cloudtruth.environment }}" labels: version: "{{ version }}" data: {%- for param in params %} {{ param.name | key_safe }}: |- {{ param.value }} {%- endfor %} {% endif -%} # # Sample CloudTruth CLI command to fetch this template: # cloudtruth --project {{cloudtruth.project}} template get "{{cloudtruth.self}}" ``` {% endcode %} #### ShellENV {% code lineNumbers="true" %} ```liquid # # Iterates through all parameters in the project # {%- for param in cloudtruth.parameters %} export {{param[0] | upcase}}="{{param[1]}}" {%- endfor %} # # # Sample CloudTruth CLI command to fetch this template: # cloudtruth --project {{cloudtruth.project}} template get "{{cloudtruth.self}}"y ``` {% endcode %} #### TFVars ```liquid ### # Sample Liquid code to list all TF parameters for project {{cloudtruth.project}} ### # {%- for x in cloudtruth.parameters %} TF_VAR_{{x[0]}}="{{x[1]}}" {%- endfor %} # # Sample CloudTruth CLI command to fetch this template: # cloudtruth --project {{cloudtruth.project}} template get "{{cloudtruth.self}}" ``` #### Java Properties ```liquid #File Updated # - #{{ "now" | date: "%Y-%m-%d %H:%M" }} # # {%- for param in cloudtruth.parameters -%} {{param[0]}}={{param[1]}} {% endfor -%} # # Sample CloudTruth CLI command to fetch this template: # cloudtruth --project {{cloudtruth.project}} template get "{{cloudtruth.self}}" ``` # Actions CloudTruth Actions allow you to sync secrets and parameters with your external sources. # Import Actions ## Overview CloudTruth Import actions allow you to directly import parameters and secrets from an Integration source. | Import Action Supported Integrations | Types | | ------------------------------------ | -------------------- | | AWS Parameter store (SSM) | String; SecureString | Configuring an import action allows you to match specific patterns in your AWS parameters store keys for import. An [AWS integration for SSM](/configuration-management/integrations/aws/parameter-store-ssm) must be created as a source to import parameters and secrets from. ### Creating an Import Action From the Actions Import page, click `Import`. 1. Provide the action a name. 2. Select a region where the parameters and secrets exist for import. 3. Click `Next`. ![Selecting a Region and Service](/files/jwfnI4RB8AD6c88n12Hw) Once you have selected the region and service, you can define the pattern matching strategy that will be used to identify the *Environment*, *Project*, and *Parameter* name for each item that is imported. You can define the pattern matching using one of two styles: 1. Mustache pattern matching allows you to define a simple expression using a familiar templating language. Note that internally this will use "greedy matching", so if your parameter name contains slashes then you will probably want to use regular expressions instead.\ \ For example: `/{{ environment }}/{{ project }}/{{ parameter }}` \\ 2. For more complex matching, you can define a Python-compatible regular expression with named capture groups. You may want to leverage a tool like [Regex101](https://regex101.com/) which allows you to build, understand, and test Python regular expressions.\ \ For example: `^/(?P[^/]+)/(?P[^/]+)/(?P.+)$` ![Defining a Pattern Matching Expression](/files/4AIIlF3Uu0RbDmSQfZ6A) To assist you in creating the pattern matching expression, you can click on the *Test* button. This will run your pattern matching against the service in the selected region and show you which content matches and which content was skipped. You can check that the correct items match, and that the extracted environment, project, and parameter name is what you expect it to be: ![](/files/itHByXkA1uQ0Fux0yD5W) Once you have defined your resource pattern click `Preview`. ![](/files/0IKuuwPksUIPNnjaHHiB) You now have the options to perform a `Dry Run` or directly `Create Import`. {% hint style="success" %} It is recommended to perform a Dry Run first, especially if you did not test your pattern. It's always good to know before hand what you will be importing! {% endhint %} #### Dry Run A dry run task ![](/files/Mw8obRdcMGuMjSgUiciD) will show you resources that will be created as part of the import. ![](/files/O4Che22B1GJw50uNSrgA) #### Create Import Running a create import will create the resources directly at action create time. ![](/files/OhKguJNf4ohfDXJpqHo3) The created import action is now displayed on the Actions Import page for the selected project(s). ![](/files/nI41m0tOpB1EhX7Z1fpo) Action information is also associated with the selected integration on the Import tab. The integration actions table displays all actions associated with the integration across all projects. ![](/files/FYhbGzTeWPeoLNGOgJTG) **Import action details** Click on an action from the import Actions page to get detailed information and tasks. Tasks are expandable and display the evaluated resource name that is used for the imported. If an action fails you will find detailed logging in the Tasks table. By default status only display tasks that contain changes to the parameters and secrets. You can use the `Only Changes` toggle to display tasks had a no-op. ![](/files/kjPsU03Qoc9bfPpaN96h) ### Managing Import Actions You can edit, initiate a sync (Dry Run), sync (Run) , or delete an action from any of the Import actions tables or on the detailed action page with the menu button. ![](/files/iq67q0SYDCeJFkR0ewF6) #### Editing an Import action You can edit the name of an action, description, and Resource pattern that defines an import. ![](/files/YbjtR1sjIxpXixDbBwWO) #### Syncing an Import action You can perform a manual sync from the import action menu. The manual sync operation allows you to perform a dry run of the Import or initiate a manual live sync. #### Deleting an Import action Deleting an Import action will retain all imported information even if the action is deleted. # Push Actions ## Overview CloudTruth push actions allow you to write secrets to an external integration from specified projects. This allows you to keep existing workflows and obtain the centralized data management CloudTruth provides. | Push Action Supported Integrations | Types | | ---------------------------------- | -------------------- | | AWS Parameter store (SSM) | String; SecureString | | AWS Secrets Store | Secret | Configuring a push action requires three prerequisites that work together to form the base of what you will be sending to the external source. 1. A CloudTruth [AWS Integration](/configuration-management/integrations/aws) created with Write Access in your organization. 2. [Parameters](/configuration-management/parameters/parameter-management/managing-parameters#adding-an-internal-parameter-value) or secrets created within a [project](/configuration-management/projects#creating-projects). 3. [Tags](/configuration-management/environments#tagging) created in an environment which act as a trigger for push. The Actions page will walk you through creating an integration of tag if they do not exist. ![](/files/y3ZaUAOIPqX2SYyGXoem) The list will dynamically change depending on what is setup in your organization and the project selected. This project has at least one parameter or secret and a tag exists within an environment. Therefore, the Actions page only displays a shortcut to create an AWS integration. ![](/files/rWuowyXUyPoG8SU4WWAb) ### Creating a Push Action From the Actions Push page, click `Create Push`. 1. Provide the action a name and a tag from your selected environments. 2. Select a project(s) that contain parameters and secrets to be pushed. 3. Select a configured integration, the region to push to and the destination service 4. Check the options desired: * `DRY RUN`: when the push action executes, it only reports the upstream changes it would perform without actually performing them * `FORCE`: By default, PUSH will not overwrite any upstream items if it didn't create it. Turning `FORCE` on allows CloudTruth to take ownership and overwrite any pre-existing items * `LOCAL`: By default, PUSH will include all parameters inherited from parent projects. Turning `LOCAL` on will cause it to only send the parameters defined directly in the given projects * The destination type automatically determines which of parameters and secrets are pushed to it, override the default with: * `PARAMETERS`: Include parameters (non-secrets) when pushing * `SECRETS`: Include secrets when pushing * `COERCE`: Include secrets/parameters even if the upstream destination doesn't allow them (e.g. non-secrets in AWS SecretsManager) 5. Click `Next`. ![](/files/JGfhiZ9Weytk9SQXFopH) You can now build the name and structure of the parameters that are being pushed. ![](/files/Mp4nVnXY7Y8o4FiHYrJb) {% hint style="info" %} When creating a resource name the string and selected template components must conform to the services naming conventions. {{parameter}} name is a required component of the Resource Name. {% endhint %} Preview the action and click `Create Action`. ![](/files/g2EEEyB7opJlYQPp13qG) The created action is now displayed on the Actions page for the selected project(s). ![](/files/z1G8Lpy4VAK7xhRN2v6N) Action information is also associated with the selected integration. The integration actions table displays all actions associated with the integration across all projects. ![](/files/zxLGN1buxZFFAQ7hhAQB) #### **Push action details** Click on an action from the Push Actions page to get detailed information and tasks. Tasks are expandable and display the evaluated resource name that is used for the created secret in the selected integration service. If an action fails you will find detailed logging in the Tasks table. ![](/files/1yZwnCKBkTwwzMMB4ySB) {% hint style="info" %} The Push action only writes CloudTruth Secrets to AWS Secrets Manager. {% endhint %} #### Action Triggers [Environment Tags](/configuration-management/environments#tagging) serve as triggers for a push action. The initial sync uses secrets and values that are associated with the selected tag when an action is created. Updating a tag to the latest time, or even a previous time, will initiate a new sync on any actions that are triggered by the updated tag. This effectively provides your external sources a sync point with a projects parameters associated with a specified tag. Actions can contain multiple tags but are limited to a single tag per environment. ### Managing Actions You can edit, initiate a sync, or delete an action from any of the actions tables or on the detailed action page with the menu button. ![](/files/lt2G2w8TB15PgrEVMwuW) #### Editing an action You can edit the name of an action, description, project(s), Resource Name and change the Tag that triggers the push. ![](/files/7oto4YdXLKokzr3YB2Nd) {% hint style="warning" %} Removing, adding or updating an associated Actions tag will trigger an update to external sources. The secrets and values will be updated or removed based on the removed, added or updated tags. {% endhint %} #### Syncing an action You can perform a manual sync from the action menu. This is useful if the action fails for connectivity or setup issues to the external source. #### Deleting an action Deleting an action will remove all parameters and secrets stored in the external integration source. #### Unsupported parameter types [External ](/configuration-management/parameters/parameter-management/external-values)and [Dynamic ](/configuration-management/parameters/parameter-management/managing-parameters#dynamic-parameters)parameter values will fail to be pushed to selected services. # CLI & API Get started accessing your configuration with the CloudTruth CLI and API. * [CloudTruth CLI installation and overview](/configuration-management/cli-and-api/cloudtruth-cli) * [Rest API](/configuration-management/cli-and-api/rest-api) # CloudTruth CLI The CloudTruth CLI tool is used for interacting with the CloudTruth configuration management service. In order to use the CLI you must have an active CloudTruth account. ## Installation The CLI is available as package with a binary executable. Download the version built for your Platform: Here are some examples on how to install the latest version of the CloudTruth CLI on your preferred distribution. The Shell Install command (preferred) will automatically detect your distribution and architecture to install the correct CloudTruth CLI installation package. {% tabs %} {% tab title="Shell (preferred)" %} The shell installer supports Linux and Darwin distros and will install the latest version. * curl {% code overflow="wrap" %} ``` curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sudo sh ``` {% endcode %} * wget {% code overflow="wrap" %} ``` wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sudo sh ``` {% endcode %} You can also specify a version by passing the --version parameter from stdin (curl example). {% code overflow="wrap" %} ``` curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sudo sh -s -- --version 1.2.0 ``` {% endcode %} {% endtab %} {% tab title="PowerShell (preferred)" %} {% hint style="info" %} Make sure the Windows execution policy is set to allow running PowerShell scripts. {% endhint %} {% hint style="warning" %} This script requires [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) or higher, if PowerShell 7 isn't available on your system, use the [Windows manual install instructions](#windows) {% endhint %} Download: {% code overflow="wrap" %} ``` Invoke-WebRequest https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.ps1 -OutFile $env:TEMP\install.ps1 ``` {% endcode %} Change directories to the download location: {% code overflow="wrap" %} ``` cd $env:TEMP ``` {% endcode %} Running the CloudTruth PowerShell installation script without parameters will install the latest version of the CloudTruth CLI: {% code overflow="wrap" %} ``` .\install.ps1 ``` {% endcode %} or, to install a specific CloudTruth CLI version: {% code overflow="wrap" %} ``` .\install.ps1 -Version ``` {% endcode %} The script will output the executable location to the console, feel free to copy it to a desired location or add the displayed location to the `$env:PATH` {% endtab %} {% tab title="Debian/Ubuntu" %} Get latest version and download: {% code overflow="wrap" %} ``` CLOUDTRUTH_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/') ``` {% endcode %} {% code overflow="wrap" %} ``` curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth_${CLOUDTRUTH_CLI_VERSION}_amd64.deb ``` {% endcode %} Install: {% code overflow="wrap" %} ``` sudo dpkg -i cloudtruth_${CLOUDTRUTH_CLI_VERSION}_amd64.deb ``` {% endcode %} {% endtab %} {% tab title="RHEL" %} {% hint style="warning" %} The installation process on RHEL7/CentOS7 requires CloudTruth CLI v1.2.1 or higher. {% endhint %} Get latest version and download: {% code overflow="wrap" %} ``` CLOUDTRUTH_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/') ``` {% endcode %} * ARM64 (aarch) {% code overflow="wrap" %} ``` curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.aarch64.rpm ``` {% endcode %} * Intel (x86\_64) {% code overflow="wrap" %} ``` curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.x86_64.rpm ``` {% endcode %} Install: * ARM64 (aarch) {% code overflow="wrap" %} ``` sudo rpm -i cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.aarch64.rpm ``` {% endcode %} * Intel (x86\_64) ``` sudo rpm -i cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.x86_64.rpm ``` {% endtab %} {% tab title="MacOS" %} Get latest version and download: {% code overflow="wrap" %} ``` export CLOUDTRUTH_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/') ``` {% endcode %} * Intel processor: {% code overflow="wrap" %} ``` curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-apple-darwin.tar.gz ``` {% endcode %} * Apple Silicon: {% code overflow="wrap" %} ``` curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-aarch64-apple-darwin.tar.gz ``` {% endcode %} Extract: {% code overflow="wrap" %} ``` tar xzf cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-apple-darwin.tar.gz ``` {% endcode %} Install: * Intel processor: {% code overflow="wrap" %} ``` sudo install -m 755 -o root "cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-apple-darwin/cloudtruth" /usr/local/bin ``` {% endcode %} * Apple Silicon {% code overflow="wrap" %} ``` sudo install -m 755 -o root "cloudtruth-$CLOUDTRUTH_CLI_VERSION-aarch64-apple-darwin/cloudtruth" /usr/local/bin ``` {% endcode %} {% endtab %} {% tab title="Windows" %} Get latest version and download: {% code overflow="wrap" %} ``` $CLOUDTRUTH_CLI_VERSION = ((Invoke-WebRequest https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest).Content | ConvertFrom-Json).tag_name ``` {% endcode %} {% code overflow="wrap" %} ``` Invoke-WebRequest -outfile $ENV:TEMP\cloudtruth.zip https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-pc-windows-msvc.zip ``` {% endcode %} Extract to temporary directory: {% code overflow="wrap" %} ``` Expand-Archive $ENV:TEMP\cloudtruth.zip -DestinationPath $ENV:TEMP ``` {% endcode %} Copy the executable (this example uses `C:\cloudtruth`) {% code overflow="wrap" %} ``` copy-item -Path $ENV:Temp\cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-pc-windows-msvc\* C:\cloudtruth\ ``` {% endcode %} Add the executable's location to the search path environment variable: {% code overflow="wrap" %} ``` $env:Path += ";C:\cloudtruth" ``` {% endcode %} {% endtab %} {% endtabs %} ## Configuration The CloudTruth CLI tool has several ways of configuring it, allowing you to pick whichever method is most suitable for your environment. With any method you will need to create a [CloudTruth API Access Token](/org-management/access-control/access-tokens) to grant the CLI access. You can configure the CLI using: * Method 1: [Environment variables](#environment-based-configuration) * Method 2: [Command-line arguments](#argument-base-configuration) * Method 3: [CloudTruth CLI configuration file](#file-based-configuration) ### Method 1: Environment-based Configuration The CloudTruth CLI can use supported `CLOUDTRUTH_` environment variables that are exported in a local shell. CloudTruth environment variables will merge with and take precedence over a configured CloudTruth configuration file. | Config Options | Usage | | ------------------------ | ----------------------------------------------------------------------- | | `CLOUDTRUTH_API_KEY` | Required: Authenticates the CLI with the provided CloudTruth API Token. | | `CLOUDTRUTH_PROFILE` | Your profile (which can contain API key, project, and environment) | | `CLOUDTRUTH_PROJECT` | Sets the targeted project. | | `CLOUDTRUTH_ENVIRONMENT` | Sets the targeted environment. | Provide your CloudTruth API Key as an environment variable: ``` export CLOUDTRUTH_API_KEY="YOUR_API_KEY" ``` ### Method **2**: Argument-based Configuration The CloudTruth CLI can be authorized directly by specifying the option `--api-key` and providing your API key: ``` cloudtruth --api-key "YOUR_API_KEY" ``` {% hint style="warning" %} You can prefix commands with a [space](https://www.linuxjournal.com/content/using-bash-history-more-efficiently-histcontrol) `" "` in order to avoid having secret values like the API Key stored in your shell history. {% endhint %} ### Method 3: File-based Configuration The CloudTruth CLI stores its configuration in the YAML format. Run `cloudtruth configuration edit` to initialize and open the configuration in your default editor. ``` --- profiles: default: api_key: another_profile: source_profile: default api_key: project: "Project1" environment: "staging" ``` You can have multiple named profiles in your configuration, allowing you to maintain multiple sets of configuration fields in the configuration file. Values can be inherited from one profile to another by setting the `source_profile` configuration field. Profiles without an explicit `source_profile` configuration implicitly inherit from the *default* profile. Use a specific profile with the `--profile` option. ``` cloudtruth --profile another-profile ``` If the `--profile` argument is not supplied, the profile named *default* will be used. Alternatively, you can use the `cloudtruth configuration profiles` command to create or edit profiles. ``` cloudtruth configuration profiles set default --api-key "YOUR_API_KEY" cloudtruth configuration profiles set demo-stage --proj MyFirstProject --env staging --desc "Demo Project Staging Environment" ``` {% hint style="info" %} The created configuration file is named *cli.yml* and resides in the standard application configuration location for your platform: * Linux -> $XDG\_CONFIG\_HOME/cloudtruth/cli.yml * macOS -> $HOME/Library/Application Support/com.cloudtruth.CloudTruth-CLI/cli.yml * Windows -> %AppData%\CloudTruth\CloudTruth CLI\config\cli.yml {% endhint %} ## Running Once you have the application configured with your CloudTruth API key, you can interact with your CloudTruth parameters. The CloudTruth CLI uses a subcommand structure to scope available actions as appropriate for a given resource. ### Switching the active CloudTruth Project and Environment #### CloudTruth Project You must select a target project for the CLI with the `--project` option: ``` cloudtruth --project YOUR_PROJECT ``` #### CloudTruth Environment By default, all commands will run against the *default* CloudTruth environment. To change the target environment, you can supply use`--env` option: ``` cloudtruth --project MyFirstProject --env YOUR_ENVIRONMENT ``` ### CloudTruth run The CloudTruth run command allows you to use parameters stored in CloudTruth and pass them through to your applications. | run options | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | -c, --command | Run this command | | --as-of | Date/time of parameter value(s) | | -i, --inherit | Handle the relationship between local and CloudTruth environments \[default: overlay] \[possible values: none, underlay, overlay, exclusive] | | r, --remove | Remove the variables from the CloudTruth environment for this run | | -s, --set | Set the variables in this run, even possibly overriding the CloudTruth environment | You can issue the `cloudtruth` run command with `printenv` to print all of your local and CloudTruth parameters. ``` cloudtruth --project MyFirstProject run --command printenv ``` #### Inheritance By default the run command will overlay all CloudTruth and local parameters into your command. You can use the `--inherit` option to change the behavior. This example will only passthrough CloudTruth parameters: ``` cloudtruth --project MyFirstProject run --inherit none --command printenv ``` #### Run time parameters The run command will also allow you to remove or set parameters to customize a specific workflow in real time. ``` cloudtruth --project MyFirstProject run --inherit none --command printenv --set NEW_VALUE=Production --remove SOME_VALUE ``` ### Usage Examples {% hint style="success" %} Listing objects such as projects, environments and parameters will return a list of names. For detailed information use the values flag`-v, --values`. {% endhint %} Create a new parameter and set a value. To mark the value as a secret use the `--secret` flag. ``` cloudtruth --project MyFirstProject parameters set PARAMETER_KEY --value SOME_VALUE ``` View a list of all parameters with values. ``` cloudtruth --project MyFirstProject parameters list --values ``` Retrieve a specific parameter value by key name ``` cloudtruth --project MyFirstProject parameter get PARAMETER_KEY ``` Retrieve overrides for specific parameter values across environments. ``` cloudtruth --project MyFirstProject parameter environment PARAMETER_KEY ``` Show differences with parameter values across two environments. ``` cloudtruth --project MyFirstProject parameter differences --env staging --env production ``` View a tree view of all environments. ``` cloudtruth --project MyFirstProject environments tree ``` Retrieve the contents of a project template. ``` cloudtruth --project MyFirstProject template get "TEMPLATE_NAME" ``` ### Command List {% hint style="success" %} You can also get auto-completions for most popular shells by running: `source <(cloudtruth completions ),` where "SHELL" is the name of your shell. {% endhint %} | Flags | Description | | ------------- | -------------------------- | | -h, --help | Prints help information | | -V, --version | Prints version information | | Options | Description | | ------------- | ------------------------------------------------------------------------ | | -k, --api-key | CloudTruth API key | | -e, --env | The CloudTruth environment to work with | | --profile | The configuration profile from the application configuration file to use | | --project | The CloudTruth project to work with |
commandsubcommandDescription
audit-logsDisplay audit logs [aliases: audit, aud, a, log, logs]
listList audit log details [aliases: ls, l]
summaryDisplay summary of audit logs [aliases: sum]
completionsGenerate shell completions for this application
configurationConfiguration options for this application [aliases: config, conf, con]
currentShow the current arguments and their sources. [aliases: curr, cur]
editEdit your configuration data for this application
profilesWork with CloudTruth CLI profiles [aliases: profile, prof, pr, p]
environmentsWork with CloudTruth environments [aliases: environment, envs, env, e]
copyCopy an environment and its children to new environment(s) [aliases: cp]
deleteDelete specified CloudTruth environment [aliases: del, d]
listList CloudTruth environments [aliases: ls, l]
setCreate/update a CloudTruth environment [aliases: s]
tagView and manipulate environment tags [aliases: ta]
treeShow a tree representation of the environments [aliases: tr, t]
helpPrints this message or the help of the given subcommand(s)
groupsUser group management commands
deleteDelete the specified CloudTruth user group
getGet detailed CloudTruth user group information
listList CloudTruth user groups
setCreate/update a Cloudtruth user group and manage group users
integrationsWork with CloudTruth integrations [aliases: integration, integrate, integ, int]
exploreExplore integrations by Fully Qualified Name (FQN). [aliases: exp, ex, e]
listList CloudTruth integrations [aliases: ls, l]
loginSets up a CloudTruth configuration profile api_key
logoutRemoves a CloudTruth configuration profile api_key
parametersWork with CloudTruth parameters [aliases: parameter, params, param, p]
copyCopy a parameter and its value [aliases: cp]
deleteDelete the parameter from the project [aliases: del, d]
differencesShow differences between properties from two environments [aliases: difference, differ, diff]
environmentShows values across environments [aliases: environ, env]
exportExport selected parameters to a known output format. Exported parameters are limited to alphanumeric and underscore in key names. Formats available are: dotenv, docker, and shell.
getGets value for parameter in the selected environment
listList CloudTruth parameters [aliases: ls, l]
setSet a value in the selected project/environment for an existing parameter or creates a new one if needed
unsetRemove a value/override from the selected project/environment and leaves the parameter in place.
projectsWork with CloudTruth projects [aliases: project, proj]
copyCopy a project and its children to new project(s) [aliases: cp]
deleteDelete specified CloudTruth project [aliases: del, d]
listList CloudTruth projects [aliases: ls, l]
setCreate/update a CloudTruth project
treeDisplay CloudTruth project inheritance [aliases: tr]
runRun a shell with the parameters in place [aliases: run, r]
templatesWork with CloudTruth templates [aliases: template, temp, t]
deleteDelete the CloudTruth template [aliases: del, d]
differencesShow differences between templates [aliases: difference, differ, diff, di]
editEdit Edit the specified template [aliases: ed, e]
getGet an evaluated template from CloudTruth
historyDisplay template history [aliases: hist, h]
listList CloudTruth templates [aliases: ls, l]
previewEvaluate the provided template without storing [aliases: prev, pre]
setSet the CloudTruth template
validateValidate a CloudTruth template [aliases: valid, val, v]
usersWork with CloudTruth users [aliases: user, us]
currentDisplay information about current user [aliases: cur, c]
deleteDelete specified CloudTruth account [aliases: del, d]
getGet detailed CloudTruth user information
invitationsManage user invitations [aliases: invitation, invite, inv, in, i]
listList CloudTruth users [aliases: ls, l]
setCreate/update a CloudTruth service account [aliases: s]
## Issue Reporting The CloudTruth CLI is open source. You can report issues and get details on building and developing locally in the CloudTruth CLI repo. {% embed url="" %} # Rest API Introduction to the CloudTruth API ## Introduction Does CloudTruth have an API? Of course we do! The CloudTruth API is the same API used by our SaaS offering. Anything that you can do in our GUI, you can do programmatically via the API. ## Overview The CloudTruth API is a pretty standard RESTful-like HTTP API. You perform GET, PUT, POST, PATCH and DELETE operations models hosted by our web service. Operations require a JWT or [API Access Token](/org-management/access-control/access-tokens) in the Authorization header of the call. Parameters are passed to the web service via JSON in the body of the request. Results are returned as JSON structures in the body of the response. Our complete REST API documentation is automatically generated and can be found here: {% embed url="" %} We also provide an interactive web interface to the API: {% embed url="" %} ## Getting Started We will start you off with a basic example of a GET operation that will list your CloudTruth Environments. From the [environment\_list](https://api.cloudtruth.io/api/schema/redoc/#operation/environments_list) schema docs we can find the GET request query parameters and typical response. ## environments\_list `GET` `https://api.cloudtruth.io/api/v1/environments/` Lists CloudTruth Environments #### Query Parameters | Name | Type | Description | | -------------- | ------- | ---------------------------------------------- | | name | string | | | page | integer | A page number within the paginated result set, | | page\_size | string | Number of results to return per page. | | parent\_\_name | string | | {% tabs %} {% tab title="200 " %} ``` { "count": 4, "next": null, "previous": null, "results": [ { "created_at": "2021-07-19T19:22:44.689825Z", "description": "The auto-generated default environment.", "id": "ad34ea7d-c9cb-473e-93fb-06dc468cacd7", "modified_at": "2021-08-02T19:17:28.920832Z", "name": "default", "parent": null, "url": "https://api.cloudtruth.io/api/v1/environments/ad34ea7d-c9cb-473e-93fb-06dc468cacd7/" } ``` {% endtab %} {% endtabs %} Now you can issue a get request with your API Access token, here is a basic example in Python and Bash to get you going. {% tabs %} {% tab title="Python" %} ```python import requests token = "Your API Access token" headers = {'Authorization': f'Api-Key {token}'} url = "https://api.cloudtruth.io/api/v1/environments/" response = requests.get(url, headers=headers) environments = response.json() print(json.dumps(environments, indent=4, sort_keys=True)) ``` {% endtab %} {% tab title="Bash" %} ``` token="Your API Access token" curl -s --header "Content-Type: application/json" \ --header "Authorization: Api-Key ${token}" \ --request GET \ https://api.cloudtruth.io/api/v1/environments/ ``` {% endtab %} {% endtabs %} You can checkout out our repo for a few additional working examples. {% embed url="" %} # Integrations Our Integrations help you quickly get started with some of your most common workflows. * [Argo CD](/configuration-management/integrations/argo-cd) * [Atlassian Compass](/configuration-management/integrations/atlassian-compass) * [AWS](/configuration-management/integrations/aws) * [Bitbucket Pipelines](/configuration-management/integrations/bitbucket-pipelines) * Circle CI * [Docker](/configuration-management/integrations/docker) * [Docker Compose](/configuration-management/integrations/docker-compose) * [GitHub](/configuration-management/integrations/github) * [GitHub Actions](/configuration-management/integrations/github-actions) * [GitLab](/configuration-management/integrations/gitlab) * [Harness](/configuration-management/integrations/harness) * [Jenkins](/configuration-management/integrations/jenkins) * [Kubernetes](/configuration-management/integrations/kubernetes) * [Pulumi](/configuration-management/integrations/pulumi) * [Terraform](/configuration-management/integrations/terraform) * [Terragrunt](/configuration-management/integrations/terragrunt) ## API Access Tokens Most of our integrations require you to have a CloudTruth API access token. You can jump to our documentation pages on [Managing Access Tokens](/org-management/access-control/access-tokens) or follow this summary below. Open the CloudTruth API administration screen by clicking `API Access` in the left hand menu: ![](/files/-McFCya6-M5FxxnQ2QPP) Generate a new token: ![](/files/98zb2GmTWmo59YanM1nu) # Argo CD How to install and use the CloudTruth Argo CD Plugin This walkthrough shows you how to use CloudTruth parameters and secrets in Argo CD directly from our Argo CD plugin. {% embed url="" %} ## Prerequisites * You are familiar with [Argo CD](https://argo-cd.readthedocs.io/en/stable/). * You have created one or more [CloudTruth Parameters](https://github.com/cloudtruth/ctdocs/blob/live/integrations/broken-reference/README.md). * You have created a [CloudTruth API Access token](https://github.com/cloudtruth/ctdocs/blob/live/integrations/broken-reference/README.md). ## CloudTruth Argo CD plugin The CloudTruth plugin solves how to handle secrets management with Argo CD. When the plugin is installed in your application it will replace any references following the format `` in your GitOps yaml files. #### Installing the plugin You can run an automated installer that will install the plugin in your Argo CD installation. ``` curl -s https://raw.githubusercontent.com/cloudtruth/argocd-cloudtruth-plugin/main/install/setup.sh | sh ``` Provide the installer with the following CloudTruth parameters: | Parameter | Value | | ------------------------------------------------------------------------------------------------- | -------------------------------------- | | [CLOUDTRUTH\_API\_KEY](/org-management/access-control/access-tokens#creating-an-api-access-token) | Provides access to your CloudTruth org | | [CLOUDTRUTH\_ENVIRONMENT](/configuration-management/environments) | Specifies a targeted Environment | | [CLOUDTRUTH\_PROJECT](/configuration-management/projects) | Specifies a targeted project | | [CLOUDTRUTH\_TAG](/configuration-management/environments#tagging) | Specifies a targeted tag | The installer will perform the following to configure the plugin in your Argo CD installation: 1. Create a K8s `secret` with the provided parameters in the Argo namespace. 2. Patch the [argocd-repo-server](https://github.com/cloudtruth/argocd-cloudtruth-plugin/blob/main/install/argocd-repo-server.patch.yaml) to add the [sidecar container](https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/#register-the-plugin-sidecar) and attach the secret 3. Restart the Argo CD repo server to pick up the changes. For a full parameters list visit our [Argo plugin repo](https://github.com/cloudtruth/argocd-cloudtruth-plugin#usage). ## Using the plugin for secrets and parameters Now that the plugin is installed, you can reference CloudTruth config in your app config files. The plugin is enabled for your argocd application in a gitops fashion by creating the file `.argocd-cloudtruth-plugin` in the root of your Application's repo, or in a subdirectory if you qualify that repo with a path. The file can be empty or contain a yaml dictionary to override the plugin's configuration for that repo. ### UI app install The new plugin sidecar mechanism prevents one from using the UI or CLI to enable a plugin if the gitops style enablement is in place. If the gitops style is not for you, you can still force enablement by [manually defining the Application manifest](https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/#using-a-config-management-plugin-with-an-application). You can still override any [installation parameter values](https://github.com/cloudtruth/argocd-cloudtruth-plugin#usage) for your specific app with parameters
### Argo CLI app installation With the new sidecar plugin scheme, the [Argo CLI](https://argo-cd.readthedocs.io/en/stable/getting_started/#2-download-argo-cd-cli) does not allow you to create apps with the plugin enabled, however, you can create an app and the plugin will automatically be enabled for it if the repo contains the trigger file `.argocd-cloudtruth-plugin` The following are a few examples of using the CloudTruth plugin with the Argo CLI. #### **App creation** [Create](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd_app_create/) an application: ``` argocd app create YOUR_APP --repo https://github.com/YOUR_REPO --path cloudtruth-plugin --dest-server YOUR_K8S_SERVER --dest-namespace default ``` Create an application and specify a specific project: ``` argocd app create YOUR_APP --repo https://github.com/YOUR_REPO --path cloudtruth-plugin --dest-server YOUR_K8S_SERVER --dest-namespace default --plugin-env CLOUDTRUTH_PROJECT=YOUR_CLOUDTRUTH_PROJECT ``` Create an application and specify a specific project and environment: ``` argocd app create YOUR_APP --repo https://github.com/YOUR_REPO --path cloudtruth-plugin --dest-server YOUR_K8S_SERVER --dest-namespace default --plugin-env CLOUDTRUTH_PROJECT=YOUR_CLOUDTRUTH_PROJECT --plugin-env CLOUDTRUTH_ENVIRONMENT=YOUR_CLOUDTRUTH_ENVIRONMENT ``` #### App updates Add the plugin to existing apps by adding the trigger file `.argocd-cloudtruth-plugin`to your Application's repo: To update a plugin parameter value to existing app: ``` argocd app set YOUR_APP --plugin-env CLOUDTRUTH_ENVIRONMENT=YOUR_CLOUDTRUTH_ENVIRONMENT ``` ## Argo CD plugin demo Here is an example use case with the Argo CD plugin that populates a ConfigMap with values pulled from CloudTruth while deploying an application in a GitOps workflow. We will deploy a flask application from our [demo Git repo](https://github.com/cloudtruth/blog-examples/tree/main/argo-flask/cloudtruth-plugin). The [ConfigMap](https://github.com/cloudtruth/blog-examples/blob/main/argo-flask/cloudtruth-plugin/flask-configmap.yaml) substitutes data values from CloudTruth using the default substitution format ``. ``` kind: ConfigMap apiVersion: v1 metadata: name: flask-map data: FLASK_APP: "" FLASK_ENV: "" FLASK_MESSAGE: "" FLASK_RUN_HOST: "" FLASK_RUN_PORT: "" IMAGE: "" ``` You can use the [CloudTruth CLI](/configuration-management/cli-and-api/cloudtruth-cli#installation) that sets up a project to deploy this example. ``` cloudtruth projects set flask cloudtruth --project flask parameters set FLASK_APP -v "flaskdemo.py" cloudtruth --project flask parameters set FLASK_DEBUG -v "True" cloudtruth --project flask parameters set FLASK_ENV -v "development" cloudtruth --project flask parameters set FLASK_MESSAGE -v "Configuration Management for default" cloudtruth --project flask parameters set FLASK_RUN_HOST -v "0.0.0.0" cloudtruth --project flask parameters set FLASK_RUN_PORT -v "3000" cloudtruth --project flask parameters set IMAGE -v CloudTruth.jpg ``` Deploy the app with the following Argo CLI command: ``` argocd app create flask --repo https://github.com/cloudtruth/blog-examples --path argo-flask/cloudtruth-plugin --dest-server https://kubernetes.default.svc --dest-namespace default --plugin-env CLOUDTRUTH_ENVIRONMENT=production ``` The `argocd app create` is broken down into the following commands. The `--plugin-env` commands specify the CloudTruth environment to get values from. The project name for the plugin is read from the `.argocd-cloudtruth-plugin` [file in the repo](https://github.com/cloudtruth/blog-examples/blob/main/argo-flask/cloudtruth-plugin/.argocd-cloudtruth-plugin). | Command | Value | | ---------------- | --------------------------------------------- | | --repo | | | --path | argo-flask/cloudtruth-plugin | | --dest-server | | | --dest-namespace | default | | --plugin-env | CLOUDTRUTH\_ENVIRONMENT=production | Verify the ConfigMap has values from the configured CloudTruth project with the `manifests` command: ``` argocd app manifests flask --- apiVersion: v1 data: FLASK_APP: flaskdemo.py FLASK_ENV: development FLASK_MESSAGE: Configuration Management for default FLASK_RUN_HOST: 0.0.0.0 FLASK_RUN_PORT: "3000" IMAGE: CloudTruth.jpg kind: ConfigMap metadata: labels: app.kubernetes.io/instance: flask name: flask-map namespace: default ``` Deploy by synching the app: ``` argocd app sync flask ``` You can also deploy and verify the app health in the Argo UI. ![](/files/ErhVLevuiggmxo6CO8Fg) # Atlassian Compass CloudTruth provides an integration with the Atlassian Compass product that allows you to see the CloudTruth Audit Log that allows you to keep on top of changes to your secrets and parameters across your team. Once the integration is installed into your Atlassian Compass portal, you can access it by navigating to any Component page, and the CloudTruth integration will be visible in the left nav for the page. The first time it is accessed by a user they will be required to input a [CloudTruth API token](/configuration-management/integrations#api-access-tokens) as shown below. Currently all users will need to supply a token rather than having a global one shared across the org.

Initial Login

Once logged in, the integration will show the CloudTruth audit log. One can view a subset of the audit log actions by picking filters from the dropdowns.
# AWS CloudTruth provides an easy and convenient way to import and export data from AWS Secrets Manager and the AWS Parameter Store. We also provide the ability to read in (import) structured data from S3 buckets. The CloudTruth to AWS Integration connection provides a way to: * Centralize the management of secrets and parameters * Stage and push changes from the centralized CloudTruth parameter store to AWS parameter and secret stores An AWS account. If you don't have one, you can sign up for a free trial [here](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank\&all-free-tier.sort-order=asc\&awsf.Free%20Tier%20Types=*all\&awsf.Free%20Tier%20Categories=*all). #### AWS Integrations CloudTruth AWS integrations allow you to pull secrets from AWS to use them in the CloudTruth Parameter store as a single source of truth. * [AWS Parameter Store](/configuration-management/integrations/aws/parameter-store-ssm) * [AWS S3](/configuration-management/integrations/aws/s3) * [AWS Secrets Manager](/configuration-management/integrations/aws/secrets-manager) # AWS Connection # AWS Role A guide to establishing a CloudTruth AWS Role. In order for CloudTruth to access AWS resources, it is necessary to create a role associated with the CloudTruth Account ID as well as the associated inline policies for the desired AWS integrations. We give you three methods for setting up your AWS role. * **Method 1:** [CloudFormation](#use-cloudformation-to-give-cloudtruth-access) * **Method 2:** [Terraform](#use-terraform-to-give-cloudtruth-access) * **Method 3:** [AWS Console](#using-the-aws-console-to-give-cloudtruth-access) The CloudTruth Account ID `609878994716` is provided to AWS when creating the CloudTruth AWS role and authorizes CloudTruth to work with your AWS account. This ID is also shown as `CloudTruth Account #` at the top of the AWS Integrations screen within the [CloudTruth application](https://app.cloudtruth.com). ![](/files/eCkElf1iTqGe7rwDnEwh) ![](/files/fpG2IRkcNAbK37WM5VBg) ## Use CloudFormation to give CloudTruth access #### Prerequisites * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) with an appropriate [AWS credential Access Key](https://console.aws.amazon.com/iam/home#/security_credentials) * User-provided **`AWS_INTEGRATION_ROLE_NAME`** (IAM role that you'll create for CloudTruth to have access to AWS) for the AWS account. {% hint style="info" %} CloudTruth provides the required **External ID** when marking an AWS integration as Pending. * [Parameter Store (SSM)](/configuration-management/integrations/aws/parameter-store-ssm) * [S3](/configuration-management/integrations/aws/s3) * [Secret Store](/configuration-management/integrations/aws/secrets-manager) {% endhint %} #### AWS CloudTruth Integration Before running the CloudFormation stack, you'll need to create the AWS integration. The integration will sit in a `pending` state until the CloudFormation stack is created. Log into CloudTruth and go to **Integrations --> AWS** Click the blue **Add AWS Account** button. ![](/files/Iqree27KBOX1ycUjwzMG) Add in the following information: * AWS Account ID: The ID of your organizations AWS account * Role Name: The role name that you're going to use when running the CloudFormation template (coming up in the next section). * Select S3, Secrets Manager, and SSM Parameter Store for CloudTruth to have access to those services in AWS. ![](/files/SWU2pwSCoplHuUFz6xhC) Copy the `External ID` from the pending CloudTruth AWS Integration. You'll use the `External ID` in the next section when running the CloudFormation stack. #### CloudFormation Stack Creation The following AWS cli command will use the CloudFormation template to create an AWS Role providing CloudTruth AWS integration access with inline policies for S3, SSM, and Secrets Manager. Execute the following [aws cloudformation create-stack](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/create-stack.html) command: * Update the `EXTERNAL_ID_FROM_CLOUDTRUTH` from the pending CloudTruth AWS account creation. * Update the integration `AWS_INTEGRATION_ROLE_NAME` value. ``` aws cloudformation create-stack --stack-name CloudTruthIntegration \ --template-url https://cloudtruth-production-packages.s3.amazonaws.com/cloudformation/cloudtruth-access/cloudTruth_AWS_access.json \ --capabilities CAPABILITY_NAMED_IAM \ --parameters ParameterKey=CloudTruthExternalId,ParameterValue=EXTERNAL_ID_FROM_CLOUDTRUTH ParameterKey=CloudTruthRoleName,ParameterValue=AWS_INTEGRATION_ROLE_NAME ``` {% hint style="warning" %} The `AWS_INTEGRATION_ROLE_NAME`provided must match the Role Name for the CloudTruth AWS account being created as outlined the screenshot below. {% endhint %} ![](/files/6nvRM2Wu1dMGBKPOwvkB) #### CloudFormation Template Repo {% embed url="" %} ## Use Terraform to give CloudTruth access #### Prerequisites * [Terraform CLI](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/aws-get-started) * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) with an appropriate [AWS credential Access Key](https://console.aws.amazon.com/iam/home#/security_credentials) * **`External ID`** from CloudTruth AWS Integration * User provided **`AWS_INTEGRATION_ROLE_NAME`** for the AWS account. {% hint style="info" %} CloudTruth provides the required **External ID** when marking an AWS integration as Pending. * [Parameter Store (SSM)](/configuration-management/integrations/aws/parameter-store-ssm) * [S3](/configuration-management/integrations/aws/s3) * [Secret Store](/configuration-management/integrations/aws/secrets-manager) {% endhint %} The following Terraform code can be used to generate the AWS role and associated policies needed for S3 , Secrets Manager and SSM Parameter store access. See the [module documentation](https://github.com/cloudtruth/terraform-cloudtruth-access/blob/master/README.md) for further customization. * Create a working directory for Terraform * Create a `main.tf` file and copy the following code snippet. ``` provider "aws" { } module "grant_cloudtruth_access" { source = "github.com/cloudtruth/terraform-cloudtruth-access" role_name = "name-the-role-as-desired-matches-that-on-cloudtruth-integration-page" external_id = "generated-external-id-from-cloudtruth-integration-page" services_enabled = ["s3", "ssm", "secrets"] } ``` To configure write access policies for [Push Actions](/configuration-management/actions/push-actions#push-action) add the following to the main.tf: ``` services_write_enabled = ["s3", "ssm", "secrets"] ``` * Update the AWS `role_name` value. * Update the `external_id` from the pending CloudTruth AWS account creation. {% hint style="warning" %} The `AWS_INTEGRATION_ROLE_NAME`provided must match the Role Name for the CloudTruth AWS account being created as outlined the screenshot below. {% endhint %} ![](/files/H7UH4R93XVxwNn9CUWKg) * Run `terraform init`. * Run `terraform apply` and provide a region. {% hint style="success" %} Your CloudTruth AWS Role and selected inline policies are now configured and can be viewed in AWS IAM Roles. {% endhint %} ## Using the AWS Console to give CloudTruth access The following steps provide a guide for creating the AWS role needed for CloudTruth access via the AWS Console. #### Prerequisites * **`External ID`** from CloudTruth AWS Integration * User provided **`AWS_INTEGRATION_ROLE_NAME`** for the AWS account. #### Go to the IAM console {% embed url="" %} ### Create an AWS Role Click on `Roles` in the left navigation. ![](/files/-MHBp0nP9Na8XOpay3nq) Click on `Create role`. ![](/files/M860CP4y3jpTrnYeoaIt) Select `Another AWS Account`. Enter the CloudTruth Account ID `609878994716`. Check the option `Require external ID` and supply the CloudTruth Generated **`External ID`** from the pending integration setup then Click `Next:Permissions`. {% hint style="info" %} CloudTruth provides the required **External ID** when marking an AWS integration as Pending. * [Parameter Store (SSM)](/configuration-management/integrations/aws/parameter-store-ssm) * [S3](/configuration-management/integrations/aws/s3) * [Secret Store](/configuration-management/integrations/aws/secrets-manager) {% endhint %} ![](/files/STMlQwD8dDTZUd4lLJ3F) Click `Next: Tags`. ![](/files/-MW4Djg_6qFuwwT6uQzq) Click `Next: Review`. ![](/files/-MHBp0nTGAkVxuipyjyz) Enter the Role name that you used in the CloudTruth account setup, and click `Create Role`. {% hint style="warning" %} The `AWS_INTEGRATION_ROLE_NAME`provided must match the Role Name for the CloudTruth AWS account being created as outlined in the screenshots below. {% endhint %} ![](/files/-Mi8Q0kPeF3iQQ18di7o) ![](/files/-MHBp0nUfJLjTL5hPoeM) ### Inline Policies {% hint style="info" %} To complete setup you will create inline policies in your new IAM Role for each selected Integration. * [Parameter Store (SSM)](/configuration-management/integrations/aws/parameter-store-ssm#ssm-parameter-store-inline-policy) * [S3](/configuration-management/integrations/aws/s3#s3-inline-policy) * [Secret Store](/configuration-management/integrations/aws/secrets-manager#ssm-parameter-store-inline-role) {% endhint %} # CloudFormation ## Creating a CloudTruth Access IAM Role via CloudFormation ### Prerequisites * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) with an appropriate [AWS credential Access Key](https://console.aws.amazon.com/iam/home#/security_credentials) * User-provided **`AWS_INTEGRATION_ROLE_NAME`** (IAM role that you'll create for CloudTruth to have access to AWS) for the AWS account. {% hint style="info" %} CloudTruth provides the required **External ID** when marking an AWS integration as Pending. * [Parameter Store (SSM)](/configuration-management/integrations/aws/parameter-store-ssm) * [S3](/configuration-management/integrations/aws/s3) * [Secret Store](/configuration-management/integrations/aws/secrets-manager) {% endhint %} #### AWS CloudTruth Integration Before running the CloudFormation stack, you'll need to create the AWS integration. The integration will sit in a `pending` state until the CloudFormation stack is created. Log into CloudTruth and go to **Integrations --> AWS** Click the blue **Add AWS Account** button. ![](/files/Iqree27KBOX1ycUjwzMG) Add in the following information: * AWS Account ID: The ID of your organizations AWS account * Role Name: The role name that you're going to use when running the CloudFormation template (coming up in the next section). * Select S3, Secrets Manager, and SSM Parameter Store for CloudTruth to have access to those services in AWS. ![](/files/SWU2pwSCoplHuUFz6xhC) Copy the `External ID` from the pending CloudTruth AWS Integration. You'll use the `External ID` in the next section when running the CloudFormation stack. #### CloudFormation Stack Creation The following AWS cli command will use the CloudFormation template to create an AWS Role providing CloudTruth AWS integration access with inline policies for S3, SSM, and Secrets Manager. Execute the following [aws cloudformation create-stack](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/create-stack.html) command: * Update the `EXTERNAL_ID_FROM_CLOUDTRUTH` from the pending CloudTruth AWS account creation. * Update the integration `AWS_INTEGRATION_ROLE_NAME` value. ``` aws cloudformation create-stack --stack-name CloudTruthIntegration \ --template-url https://cloudtruth-production-packages.s3.amazonaws.com/cloudformation/cloudtruth-access/cloudTruth_AWS_access.json \ --capabilities CAPABILITY_NAMED_IAM \ --parameters ParameterKey=CloudTruthExternalId,ParameterValue=EXTERNAL_ID_FROM_CLOUDTRUTH ParameterKey=CloudTruthRoleName,ParameterValue=AWS_INTEGRATION_ROLE_NAME ``` {% hint style="warning" %} The `AWS_INTEGRATION_ROLE_NAME`provided must match the Role Name for the CloudTruth AWS account being created as outlined the screenshot below. {% endhint %} ![](/files/6nvRM2Wu1dMGBKPOwvkB) #### CloudFormation Template Repo {% embed url="" %} # Terrraform # AWS Console # Parameter Store (SSM) This AWS integration allows you to configure CloudTruth External Parameters from your AWS Parameter Store. ## Adding Integrations {% hint style="info" %} If you already have a CloudTruth AWS integration you can add AWS SSM by editing the existing account, selecting this integration and adding the [SSM inline policy](#ssm-parameter-store-inline-policy). The [Terraform](/configuration-management/integrations/aws/setup-aws-role#use-terraform-to-give-cloudtruth-access) and [CloudFormation](/configuration-management/integrations/aws/setup-aws-role#use-cloudformation-to-give-cloudtruth-access) role setup methods automatically create the SSM inline policy. {% endhint %} To create a new or additional AWS account click `Add AWS Account` from the Integrations AWS page to bring up the add account pane. Add a name for the AWS account, your specific AWS account ID and the AWS account role name. CloudTruth allows you to select regions where your resources exist, all US regions are enabled by default. The SSM Parameter store integration supports [CloudTruth push actions](/configuration-management/actions/push-actions#push-action). To enable Push Actions select `Write Access` for the integration and apply the [write access inline policy for SSM](#ssm-parameter-store-inline-policy). Check the SSM Parameter Store integration and click `Save`. ![](/files/JmqXhogzRqKojH3aKRPi) The AWS account will enter an Integration Error state until the AWS role is configured. An auto generated **External Id** will be created to use in the [AWS Role Creation](/configuration-management/integrations/aws/setup-aws-role). ![](/files/5VXmQR1RcGRtCv9Q47z8) #### Configuring the AWS Role With the provided **External ID** create your AWS Role. {% content-ref url="/pages/-MWATLnEfo1hmkQ4RC3m" %} [AWS Role](/configuration-management/integrations/aws/setup-aws-role) {% endcontent-ref %} ## SSM Parameter Store Inline Policy Adding an Inline Policy to the AWS Role allows CloudTruth secure access to the selected integration service. The inline policy is automatically created if you used [CloudFormation](/configuration-management/integrations/aws/setup-aws-role#use-cloudformation-to-give-cloudtruth-access) or [Terraform](/configuration-management/integrations/aws/setup-aws-role#use-terraform-to-give-cloudtruth-access) to create the role. From the [AWS IAM Console](https://console.aws.amazon.com/iam/home) select the role that you created for CloudTruth access. ![](/files/HsRbyHok5GZ3rybpqrYp) Click `Add Inline Policy`. ![](/files/Qx6aR2hlUe0wkqkuXYux) Click the `JSON` Tab. ![](/files/4eBX1kKs9aurLuzPAFcg) Paste in the following JSON for the SSM Parameter Store integration policy and click `Review Policy`. #### External Parameter Policy ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ParameterAccess", "Action": [ "ssm:DescribeParameters", "ssm:GetParameter", "ssm:GetParameters", "ssm:GetParametersByPath" ], "Effect": "Allow", "Resource": "*" } ] } ``` #### Write Access Parameter Policy for [Push Actions](/configuration-management/actions/push-actions#push-action) ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ParameterAccess", "Action": [ "ssm:AddTagsToResource", "ssm:DeleteParameter", "ssm:DescribeParameters", "ssm:GetParameter", "ssm:GetParameters", "ssm:ListTagsForResource", "ssm:PutParameter", "ssm:RemoveTagsFromResource", "tag:GetResources" ], "Effect": "Allow", "Resource": "*" } ] } ``` Type in a name for the policy and click `Create Policy`. ![](/files/sxElxUQuSec2Ax1o6N7t) {% hint style="success" %} :clap:Setup is now complete for both the AWS Role and Policy. After refreshing by clicking "Check Integration Status" the CloudTruth integration will now show as "Connected", and you can begin creating [External Parameter values](https://app.gitbook.com/@cloudtruth/s/staging/~/drafts/-MVXd5xAL1NKUBwPEBhY/configuration-management/parameters/using-dynamic-values/@drafts) that reference your AWS resources. {% endhint %} # S3 This AWS integration allows you to configure CloudTruth External Parameters from an S3 bucket. ## Adding Integrations {% hint style="info" %} If you already have a CloudTruth AWS integration you can add AWS S3 by editing the existing account, selecting this integration and adding the[ S3 inline policy](#s3-inline-policy). The [Terraform](/configuration-management/integrations/aws/setup-aws-role#use-terraform-to-give-cloudtruth-access) and [CloudFormation](/configuration-management/integrations/aws/setup-aws-role#use-cloudformation-to-give-cloudtruth-access) role setup methods automatically create the S3 inline policy. {% endhint %} To create a new or additional AWS account click `Add AWS Account` from the Integrations AWS page to bring up the add account pane. Add a name for the AWS account, your specific AWS account ID and the AWS account role name. CloudTruth allows you to select regions where your resources exist, all US regions are enabled by default. Check the S3 integration and click `Save`. ![](/files/y3lolgUx47sJ1Y0NqeFj) The AWS account will enter an Integration Error state until the AWS role is configured. An auto generated **External Id** will be created to use in the [AWS Role Creation](/configuration-management/integrations/aws/setup-aws-role). ![](/files/-Mk8iEykeQ8D1tgJyu_p) #### Configuring the AWS Role With the provided External ID create your AWS Role. {% content-ref url="/pages/-MWATLnEfo1hmkQ4RC3m" %} [AWS Role](/configuration-management/integrations/aws/setup-aws-role) {% endcontent-ref %} ## S3 Inline Policy Adding an Inline Policy to the AWS Role allows CloudTruth secure access to the selected integration service. The inline policy is automatically created if you used [CloudFormation](/configuration-management/integrations/aws/setup-aws-role#use-cloudformation-to-give-cloudtruth-access) or [Terraform](/configuration-management/integrations/aws/setup-aws-role#use-terraform-to-give-cloudtruth-access) to create the role. From the [AWS IAM Console](https://console.aws.amazon.com/iam/home) select the role that you created for CloudTruth access. ![](/files/-Mk8iHajFzFlIiwg8yIn) Click `Add Inline Policy`. ![](/files/eWXtFkich939j0OknCMP) Click the `JSON` Tab. ![](/files/4eBX1kKs9aurLuzPAFcg) Paste in the following JSON for the S3 integration policy and click `Review Policy`. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "BucketSelection", "Action": [ "s3:ListAllMyBuckets" ], "Effect": "Allow", "Resource": "*" }, { "Sid": "BucketAccess", "Action": [ "s3:GetBucketLocation", "s3:ListBucket", "s3:GetObject" ], "Effect": "Allow", "Resource": "*" } ] } ``` Type in a name for the policy and click `Create Policy.` ![](/files/sxElxUQuSec2Ax1o6N7t) {% hint style="success" %} :clap:Setup is now complete for both the AWS Role and Policy. After refreshing by clicking "Check Integration Status" the CloudTruth integration will now show as "Connected", and you can begin creating external [Dynamic Parameter](/configuration-management/parameters/parameter-management/managing-parameters#dynamic-parameters) values that reference your AWS resources. {% endhint %} # Secrets Manager This AWS integration allows you to configure CloudTruth External Parameters from your AWS Secrets Manager. ## Adding Integrations {% hint style="info" %} If you already have a CloudTruth AWS integration you can add AWS Secrets Manager by editing the existing account, selecting this integration and adding the [Secrets Manager Inline Policy](#ssm-parameter-store-inline-role). The [Terraform](/configuration-management/integrations/aws/setup-aws-role#use-terraform-to-give-cloudtruth-access) and [CloudFormation](/configuration-management/integrations/aws/setup-aws-role#use-cloudformation-to-give-cloudtruth-access) role setup methods automatically create the Secrets Manager inline policy. {% endhint %} To create a new or additional AWS account click `Add AWS Account` from the Integrations AWS page to bring up the add account pane. Add a name for the AWS account, your specific AWS account ID and the AWS account role name.‌ CloudTruth allows you to select regions where your resources exist, all US regions are enabled by default. The Secrets Manager integration supports [CloudTruth push actions](/configuration-management/actions/push-actions#push-action). To enable Push Actions select `Write Access` for the integration and apply the [write access inline policy for Secrets Manager](#ssm-parameter-store-inline-role). Check the AWS Secret Manager integration and click `Save`.​‌ ![](/files/NBGKGx6AKL6akWSzpIrB) The AWS account will enter an Integration Error state until the AWS role is configured. An auto generated **External Id** will be created to use in the [AWS Role Creation](/configuration-management/integrations/aws/setup-aws-role). ![](/files/iXrdrpkyilFtAejGwW3Z) #### Configuring the AWS Role With the provided **External ID** create your AWS Role. {% content-ref url="/pages/-MWATLnEfo1hmkQ4RC3m" %} [AWS Role](/configuration-management/integrations/aws/setup-aws-role) {% endcontent-ref %} ## AWS Secret Store Inline Policy ‌Adding an Inline Policy to the AWS Role allows CloudTruth secure access to the selected integration service. The inline policy is automatically created if you used [CloudFormation](/configuration-management/integrations/aws/setup-aws-role#use-cloudformation-to-give-cloudtruth-access) or [Terraform](/configuration-management/integrations/aws/setup-aws-role#use-terraform-to-give-cloudtruth-access) to create the role. From the [AWS IAM Console](https://console.aws.amazon.com/iam/home) select the role that you created for CloudTruth access. ![](/files/TChDNuu5pdcxOc86AejG) Click `Add Inline Policy`.​ ![](/files/-Mk8iGDDmz8qnPYMCBlA) Click the `JSON` Tab.​‌ ![](https://gblobscdn.gitbook.com/assets%2F-MV-6u23cOGf1BMdpRn4%2F-MVwf4ns5UC4IuxFJ1rz%2F-MVwhrTEZ933AuVaoOa4%2FPrtScr%20capture_5.jpg?alt=media\&token=853b9d90-de61-4947-9d33-5b28a22c38c1) Paste in the following JSON for the AWS Secret Store integration policy and click `Review Policy`. #### External Parameter Policy ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ListSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "SecretAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": "*" } ] } ``` #### Write Access Parameter Policy for [Push actions](/configuration-management/actions/push-actions#push-action) ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ListSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "SecretAccess", "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:DeleteSecret", "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret", "secretsmanager:TagResource", "secretsmanager:UpdateSecret" ], "Resource": "*" } ] } ``` Type in a name for the policy and click `Create Policy`.​‌​ {% hint style="success" %} :clap:Setup is now complete for both the AWS Role and Policy. After refreshing by clicking "Check Integration Status" the CloudTruth integration will now show as "Connected", and you can begin creating [External Parameter values](https://app.gitbook.com/@cloudtruth/s/staging/~/drafts/-MVXd5xAL1NKUBwPEBhY/configuration-management/parameters/using-dynamic-values/@drafts) that reference your AWS resources. {% endhint %} # Azure Key Vault Azure Key Vault stores secrets that can be retrieved by virtual machines and containers running in Azure to manage dynamic application configuration. When you integrate CloudTruth with your Azure Account, CloudTruth will exist in your Azure Active Directory as an Enterprise Application, and will show up in the list of service principals that you can assign access rights to. ## Prerequisites * An Azure account. If you don't have one, you can sign up for a free trial [here](https://azure.microsoft.com/en-us/free/). * A Microsoft business email account. For registering Azure to CloudTruth, a personal Outlook email account will not work. ## Registering the CloudTruth Application When you add an Azure Key Vault integration, the CloudTruth application will be registered into your Azure account. CloudTruth does not create any additional resources in your Azure account, and CloudTruth cannot access any resources unless you explicitly grant that access using Azure IAM. This application registration can added only with your consent. To initiate that consent, add an Azure Key Vault integration (in this example, we'll add one to the "Tuono" organization): ![CloudTruth - Azure Key Vault Integration](/files/78O7XIKPuyftPoqGhbbv) After you authenticate with Azure you will be presented with a consent form to register the CloudTruth application in your Azure account: ![Azure OAuth2 Application Install Consent Form](/files/311vQ7EYgBfElkMKjFps) Please note that at the time of writing this, you must use an Office 365 business account. You cannot use a personal Outlook account to register. Once you consent to registering the application, you are returned to the CloudTruth application where you can supply the Key Vault name that you want CloudTruth to use: ![Selecting the Key Vault](/files/I6CUhMY2xHCqubI7mGTk) Finally, once you submit this form, CloudTruth will finalize the integration and test the Key Vault access to see if permissions are correct. For a Key Vault that exists, but has not yet had the Azure IAM permissions updated, it may look like this: ![Integration Error: No Permission](/files/ArPIWeT8vJekPndyv43L) ## Configuring Azure Access Control Azure Key Vaults have two types of access policies. In either case you need to grant the CloudTruth application secrets access to your Key Vault. We recommend you use Azure Role Based Access Control, however either mode will work. In the following example the Key Vault is using Azure Role-Based Access Control: ![Selecting Azure Role Based Access Control](/files/zjSM7VzFzfsM9QIJKThv) In the Azure Portal console if you navigate to your Key Vault, you can add a Role Assignment for the CloudTruth application so that it can access your data. If you are using Azure Role Based Access Control follow these instructions, otherwise you can add secrets access through the Access Policies page: ![Azure Portal: Key Vault IAM](/files/SwZQFszYMv1JitPiCPQb) Select a role for CloudTruth. Be sure to choose one of the correct roles for secrets access: ![Azure Key Vault Secrets Roles](/files/EsczD1LaK2eUXqeOSSoX) Then select the CloudTruth application: ![Assigning an Azure IAM Role](/files/4u7DOvDyE9p4SmSxBgJj) Now back in the CloudTruth application, click the status refresh icon next to the integration error: ![Status Refresh](/files/upUi7U8ICDdK02znzQVu) If you configured access control properly, the integration status will show as Connected: ![Connected Integration](/files/s1atZiDjkzhahuMduNpg) Now you can use [import ](/configuration-management/actions/import-actions)or [push ](/configuration-management/actions/push-actions)actions to move content from and to your Key Vault. ## Removing the Integration In the CloudTruth portal you can delete the Key Vault integration. In the Azure Console you can navigate to: * Azure Active Directory * App Registrations * CloudTruth From there, you can delete the registration in your Azure account. # Bitbucket Pipelines This walkthrough shows you how to use CloudTruth parameters with Bitbucket Pipelines. ## Prerequisites * You have a [Bitbucket account](https://id.atlassian.com/login?application=bitbucket\&continue=https%3A%2F%2Fbitbucket.org%2Faccount%2Fsignin%2F%3FredirectCount%3D1%26next%3D%252F). * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API Access token](/configuration-management/integrations#api-tokens). ## Provide Bitbucket Pipelines CloudTruth Access You can get started with Bitbucket using a [starter pipeline template](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/). Add your generated CloudTruth API access token as a [Bitbucket repository variable](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/) named`CLOUDTRUTH_API_KEY` in your **Repository settings** > ***Pipelines*** > **Repository variables**. This allows the Bitbucket repository to securely access parameters stored in CloudTruth across all deployment environments. ![](/files/pe2kVshIYFUQMKmQtY1H) ## Configure a Bitbucket Pipeline with CloudTruth Parameters ### Using the CloudTruth CLI You can install the CLI with the following code snippet as part of a Bitbucket step in *bitbucket-pipelines.yml*. This will install the latest supported version and also verify the CLI is installed correctly by printing the version. We then use the CloudTruth CLI run command to print only CloudTruth variables that can now be accessed in your pipeline. ``` image: atlassian/default-image:2 pipelines: default: - step: name: 'Install CloudTruth CLI:' script: - (curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh || wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh) | sh - cloudtruth -V - cloudtruth --project MyFirstProject run -i none -- printenv ``` Running this pipeline will install the CloudTruth CLI and print parameter values retrieved from CloudTruth. ![](/files/qW52xCDlKmC8N4Y4x7j4) ### ### Passing CloudTruth parameters across Bitbucket Pipeline steps You can use variables across Bitbucket pipeline steps by creating an export formatted environment file and storing the file using [Bitbucket artifacts](https://support.atlassian.com/bitbucket-cloud/docs/use-artifacts-in-steps/). This snippet uses the CloudTruth CLI to create an export dotenv file with values pulled from CloudTruth. ``` - cloudtruth --project MyFirstProject parameter export shell --export > dotenv # Passes environment variables between stages artifacts: - dotenv ``` ### Using CloudTruth parameters across Bitbucket Pipeline steps In future pipeline steps you can source the dotenv artifact. The command `source dotenv` will execute the dotenv export allowing you to reference the variables in downstream stages without the CloudTruth CLI. ``` - step: name: 'CloudTruth Variables Deployment to Staging' deployment: staging script: - echo "Test CloudTruth Staging Step" - source dotenv - printenv ``` The complete **bitbucket-pipelines.yml** passing variables between steps. ``` image: atlassian/default-image:2 pipelines: default: - step: name: 'Install CloudTruth CLI:' script: - (curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh || wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh) | sh - cloudtruth -V - cloudtruth --project MyFirstProject run -i none -- printenv - cloudtruth --project MyFirstProject parameter export shell --export > dotenv # Passes environment variables between stages artifacts: - dotenv - step: name: 'CloudTruth Variables Deployment to Staging' deployment: staging script: - echo "Test CloudTruth Staging Step" - source dotenv - printenv ``` Running this pipeline will install the CloudTruth CLI and print the parameter values across multiple steps. ![](/files/-MXZX8zFNsS9MWBwCuvp) # Docker This walkthrough will show you two methods of using CloudTruth to pass environment variables to a Docker container. The first method installs the CloudTruth CLI directly in your docker image, the second method uses a CloudTruth environment file with docker run. * Method 1: [Docker CloudTruth CLI](#docker-cloudtruth-cli) * Method 2: [Docker Environment File](#docker-environment-file) ## Prerequisites * Working knowledge of Docker. * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API token](/configuration-management/integrations#api-tokens). ## Method 1: Docker CloudTruth CLI The CloudTruth CLI can be installed as part of your docker Linux container. ``` # Install the CloudTruth CLI RUN (curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh || wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh) | sh ``` This is an example `CMD` that will print the environment variables from the container environment. ``` CMD ["cloudtruth", "--project", "MyFirstProject", "run", "--", "printenv"] ``` To try this out, create a new directory called `tutorial`. Inside the directory make a new `Dockerfile` with the following contents. Depending on your container image you may need to install curl or wget. ``` FROM alpine # Install the CloudTruth CLI RUN (curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh || wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh) | sh CMD ["cloudtruth", "--project", "MyFirstProject", "run", "--", "printenv"] ``` Now you can build the image from your directory. ``` docker build -t tutorial . ``` Run your tutorial Docker image and pass in the CloudTruth API key to allow CloudTruth to authenticate in the container instance. This will print your CloudTruth Parameters and container environment variables. ``` docker run -it --rm -e CLOUDTRUTH_API_KEY="YOUR_API_KEY" tutorial ``` {% hint style="info" %} You can also export the CloudTruth API key to your local environment and then pass the key into the container without specifying the key value. ``` export CLOUDTRUTH_API_KEY="YOUR_API_KEY" docker run -it --rm -e CLOUDTRUTH_API_KEY tutorial ``` {% endhint %} ## Method 2: Docker Environment File You can also use CloudTruth Parameters inside a Docker container by using [`Docker run --env-file`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) and passing parameters with the `cloudtruth parameter export docker` CloudTruth CLI command from your local environment. You can create an environment file with the CloudTruth CLI. ``` cloudtruth --project MyFirstProject parameter export docker > dotenv ``` The `dotenv` file can now be passed to Docker with the `--env-file` flag. This will pull down an alpine container, issue the `printenv` command and display your CloudTruth parameters and container environment variables. ``` docker run -it --rm --env-file dotenv alpine printenv ``` This can also be accomplished in a single line using Bash substitution and embedding the CloudTruth CLI command directly in Docker run. ``` docker run -it --rm --env-file <(cloudtruth --project MyFirstProject parameter export docker) alpine printenv ``` # Docker Compose This walkthrough will show you two methods of using CloudTruth to pass environment variables to a Docker container with Docker Compose. The first method uses an environment file and the second method uses the CloudTruth run command. * Method 1: [Docker Compose Environment File](#docker-compose-environment-file) * Good for injecting environment variables into a container * Method 2: [Docker Compose with CloudTruth Run](#docker-compose-with-cloudtruth-run) * Good for injecting environment variables into a container * [#method-3-docker-compose-with-init-container](#method-3-docker-compose-with-init-container "mention") * Good for rendering templates as files in a container ## Prerequisites * Working knowledge of Docker and Docker-Compose. * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API token](/configuration-management/integrations#api-tokens). ## Method 1: Docker Compose Environment File You can also use CloudTruth Parameters with Docker Compose by using [`env_file`](https://docs.docker.com/compose/environment-variables/#the-env_file-configuration-option) and creating an Environment file with CloudTruth CLI `cloudtruth parameter export docker`. Inside your Docker folder create an environment file with the CloudTruth CLI. ``` cloudtruth --project MyFirstProject parameter export docker > dotenv ``` Create a `Dockerfile` with the following contents. ``` FROM alpine CMD ["printenv"] ``` With the Dockerfile that you created above, create a new container image called `cloudtruth` ``` docker build -t cloudtruth . ``` Create a `docker-compose.yml` and copy the following snippet. The `env_file` specified will import all environment variables to use with Docker compose. ``` services: app: build: . image: cloudtruth container_name: ct-test env_file: - dotenv ``` Issuing the following command will build the Docker container and issue the `printenv` command which will display all of the parameters passed in the dotenv file that are now sourced and available to use within your Docker environment. ``` docker-compose up ``` You'll see an output to the terminal with your parameters, similar to the output below. ``` Creating ct-test ... done Attaching to ct-test ct-test | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ct-test | HOSTNAME=16569452923f ct-test | FLASK_APP=flaskdemo.py ct-test | FLASK_DEBUG=True ct-test | FLASK_ENV=development ct-test | FLASK_MESSAGE=Configuration Management for Default ct-test | FLASK_RUN_HOST=0.0.0.0 ct-test | FLASK_RUN_PORT=3000 ct-test | HOME=/root ct-test exited with code 0 ``` #### #### Passing variables using the --env-flag file Alternatively, the created `dotenv` file can be passed to Docker-Compose with the `--env-file` flag. This allows you to [set specific variables](https://docs.docker.com/compose/environment-variables/#set-environment-variables-in-containers) for your app in `docker-compose.yml`. ``` services: app: build: . image: cloudtruth container_name: ct-test environment: - FLASK_ENV ``` Now you pass the `--env-file` where only the specified variables are displayed. ``` docker-compose --env-file dotenv up ``` ``` Starting ct-test ... done Attaching to ct-test ct-test | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ct-test | HOSTNAME=ac37b482be46 ct-test | FLASK_ENV=development ct-test | HOME=/root ct-test exited with code 0 ``` ## Method 2: Docker Compose with CloudTruth Run This method will use the cloudtruth CLI to add CloudTruth parameters to the environment docker-compose runs in, allowing you to inject the values into the services controlled by docker-compose. Create a `Dockerfile` with the following contents. ``` FROM alpine CMD ["printenv"] ``` The `docker-compose.yml` allows you to [set specific variables](https://docs.docker.com/compose/environment-variables/#set-environment-variables-in-containers) for your app. For example, you can create variables/parameters for a Flask app, which are created in CloudTruth. ``` services: app: build: . image: cloudtruth container_name: ct-test environment: - FLASK_ENV - FLASK_APP - FLASK_RUN_PORT ``` Now execute `docker-compose up` with the `cloudtruth run` command which will pass your CloudTruth parameters to Docker compose and display the variables selected. ``` cloudtruth --project MyFirstProject run -- docker-compose up Starting ct-test ... done Attaching to ct-test ct-test | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ct-test | HOSTNAME=4ac024aae550 ct-test | FLASK_ENV=development ct-test | FLASK_APP=flaskdemo.py ct-test | FLASK_RUN_PORT=3000 ct-test | HOME=/root ct-test exited with code 0 ``` ## Method 3: Docker Compose with init container This method will use the CloudTruth init (sidecar) container to render templates into a volume(s) shared with the target services in your docker-compose file. Source code for the CloudTruth init container: This example injects a simple static HTML page into an nginx container. The static HTML page is stored as a template in CloudTruth. ### Add a target to the template The init container will scan the specified project and environment for all templates with a special comment on the first line that specifies the file to render the template to. It must be on the first line and it looks like this: ``` #~ target: /usr/share/nginx/html/index.html ``` For this example, CloudTruth created a template named \`DEMO\_PAGE\` in project "MyFirstProject", but feel free to change the project name based on your use case. The template references the automatic parameter "cloudtruth.environment", which will insert the name of the environment the template was pulled from. You'll notice that the template has the special comment as the first line: \`#\~ target: ...\`. The init container will find this template and render it to "/usr/share/nginx/html/index.html". Here is the template: ``` #~ target: /usr/share/nginx/html/index.html {{ cloudtruth.environment }}

This is the {{ cloudtruth.environment }} web page.

``` ### Create docker-compose file This example uses the public nginx container image, but you can replace this with your own container image. Create a docker-compose.yml file or use one you already have. There are three important pieces to note, that make this whole solution work: 1. Include the `cloudtruth/templates` image as a service in the docker-compose file. You will see that listed as the web\_init service in the example file below. 2. One or more named volumes shared between the target container (web) and the init container (web\_init). In this case, we use the "static-content" named volume. Be sure to mount the named volumes to the same location in both the init container and the target container. 3. Add the \`depends\_on\` stanza to the container you want to inject the template into. The target container (web) should depend on the CloudTruth init container (web\_init) The full docker-compose.yml file for this example: ``` --- services: web_init: container_name: ctdemo-init environment: - CLOUDTRUTH_API_KEY=${CLOUDTRUTH_API_KEY} - CLOUDTRUTH_ENVIRONMENT=${CLOUDTRUTH_ENVIRONMENT:-production} - CLOUDTRUTH_PROJECT=${CLOUDTRUTH_PROJECT:-default} image: cloudtruth/templates volumes: - static-content:/usr/share/nginx/html web: container_name: ctdemo depends_on: web_init: condition: service_completed_successfully image: nginx:1.20-alpine ports: - "8585:80" volumes: - static-content:/usr/share/nginx/html volumes: static-content: ``` ### Run docker-compose up You will need to set a few environment variables for this exercise: * \`CLOUDTRUTH\_API\_KEY\` = your APi-Key * \`CLOUDTRUTH\_PROJECT\` = the project you want to render templates from * \`CLOUDTRUTH\_ENVIRONMENT\` = the environment you want to use values from to render into the template Now run docker-compose: ``` docker-compose up ``` ### Verify the results After a few seconds, the nginx container should be running with the web page hosted at In this case, I ran with \`CLOUDTRUTH\_ENVIRONMENT=production\` and can see that reflected in the web page: ![](/files/osmqhWqhsjY6yMYCsp9R) # GitHub This walkthrough shows you how to use our GitHub integration add CloudTruth External parameters from GitHub. ## Prerequisites * You have a [GitHub account](https://github.com/join). * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API Access token](/configuration-management/integrations#api-tokens). ## Connecting CloudTruth to a GitHub Repo Navigate to the GitHub integration in the CloudTruth app and click `Manage GitHub Access`. ![](/files/-Mi8Q-lCRzGWws4zzYwl) This will bring you to a GitHub login where you will authenticate with your GitHub account. ![](/files/-MW4DiWImrbYA_lGfOlq) Select a GitHub account to install the CloudTruth App. ![](/files/dn0bke4sbUwoQDK1GArS) The installation will bring you to the Github application settings. You can install CloudTruth with the following permissions on All repos or you can be selective to specific repositories. ![](/files/taWjabkv2oRAd3ByXhw9) Once the GitHub CloudTruth application is installed you will be redirected back to CloudTruth where the integration will be displayed. ![](/files/-Mi8Pw8nXWXm_7DYZoZe) {% hint style="success" %} Congrats:clap:You are now able to assign [External CloudTruth Parameters](/configuration-management/parameters/parameter-management/external-values) from GitHub that are provided in yaml and json file types. {% endhint %} # GitHub Actions How to use the CloudTruth configure-action This walkthrough shows you how to use CloudTruth parameters safely and securely with GitHub Actions using our [configure-action](https://github.com/marketplace/actions/cloudtruth-configure). ## Prerequisites * You have a [GitHub account](https://github.com/join). * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API Access token](/configuration-management/integrations#api-tokens). ## Update GitHub Repository Secrets Adding your CloudTruth API access token as a GitHub secret allows GitHub Actions to reference the API token when running a workflow. This allows you to bring configuration and secrets from your CloudTruth projects into GitHub workflows. In your GitHub repository settings, add a new repository secret with the name `CLOUDTRUTH_TOKEN` that contains your API access token as the value: ![Adding a Repository Secret](/files/n2CnOJdbhRIZePCFcfbY) ### Using [cloudtruth/configure-action](https://github.com/marketplace/actions/cloudtruth-configure) The [action](https://github.com/marketplace/actions/cloudtruth-configure) can be used to inject the configuration and secrets from a project's environment into your GitHub workflow. Within the same job, steps following the action will have environment variables set to those in your project, based on the environment you choose: ```yaml --- name: 'demo' on: pull_request: {} jobs: demo: runs-on: ubuntu-latest steps: - uses: cloudtruth/configure-action@v2.0.0 with: apikey: "${{ secrets.CLOUDTRUTH_TOKEN }}" project: MyFirstProject environment: default - name: dump the environment run: | printenv | sort ``` GitHub Action [results](https://github.com/cloudtruth/configure-action/actions/workflows/demo.yml) will show the environment variables that were added to the job, and which parameters were redacted. {% hint style="info" %} The output below comes from the configure-action repository and shows a run from parameters that were pre-configured for the configure-action demo script - your output will match the parameters you created. {% endhint %} ![Example workflow result](/files/-MaccLaRSvos0wnDjqH2) A complete example is found in the [demo workflow](https://github.com/cloudtruth/configure-action/blob/main/.github/workflows/demo.yml) of the configure-action repository. # GitLab This walkthrough shows you how to use CloudTruth parameters with GitLab CI /CD jobs. ## Prerequisites * You have a [GitLab account](https://gitlab.com/users/sign_in). * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API Access token](/configuration-management/integrations#api-tokens). ## Provide GitLab Access Add your generated CloudTruth API Access token as a GitLab variable called `CLOUDTRUTH_API_KEY` in your project settings. This allows the GitLab project to securely access parameters stored in CloudTruth. ![](/files/pTYk96mOzRxUSLrkGeHG) ## Configure a CI/CD pipeline with CloudTruth Parameters #### Install the CloudTruth CLI with a Build Stage You can install the CLI with the following code snippet in a GitLab build stage. This will install the latest supported version and also verify the CLI is installed correctly by printing the version. ``` Install CloudTruth CLI: stage: build script: - curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sh - cloudtruth -V ``` #### Passing CloudTruth parameters to GitLab test stages In the build stage, we can access and pass variables to GitLab with [artifacts](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html#artifactsreportsdotenv). This snippet will add environment variables `FLASK RUN PORT` and `FLASK_MESSAGE` to build.env with values pulled from CloudTruth. ``` # Adds CloudTruth Values to build.env file to be passed with artifacts.reports.dotenv - echo "FLASK_RUN_PORT=$(cloudtruth --project MyFirstProject --env default parameters get FLASK_RUN_PORT)" >> build.env - echo "FLASK_MESSAGE=$(cloudtruth --project MyFirstProject --env default parameters get FLASK_MESSAGE)" >> build.env # Passes environment variables between stages artifacts: reports: dotenv: build.env ``` #### Using CloudTruth parameters in test stages Now you can reference the variables in downstream stages. ``` Using CloudTruth Variables: stage: test script: - echo $FLASK_RUN_PORT - echo $FLASK_MESSAGE dependencies: - "Install CloudTruth CLI" ``` Running this pipeline will install the CloudTruth CLI and print the parameter values. ![](/files/glJbS84ehBoxT1osijWj) The complete **.gitlab-ci.yml** ``` Install CloudTruth CLI: stage: build script: - curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sh - cloudtruth -V # Adds CloudTruth Values to build.env file to be passed with artifacts.reports.dotenv - echo "FLASK_RUN_PORT=$(cloudtruth --project MyFirstProject --env default parameters get FLASK_RUN_PORT)" >> build.env - echo "FLASK_MESSAGE=$(cloudtruth --project MyFirstProject --env default parameters get FLASK_MESSAGE)" >> build.env # Passes environment variables between stages artifacts: reports: dotenv: build.env Using CloudTruth Variables: stage: test script: - echo $FLASK_RUN_PORT - echo $FLASK_MESSAGE dependencies: - "Install CloudTruth CLI" ``` #### Parameter export Alternatively you can use the CloudTruth parameter export command to create a [GitLab `.env` file](https://docs.gitlab.com/ee/ci/variables/#pass-an-environment-variable-to-another-job). GitLab pipelines will fail to upload a `.env` file if it has a newline at the end of the file. We will use a sed command in the job to strip the export of empty lines. `sed -i '/^$/d' build.env` ``` Install CloudTruth CLI: stage: build script: - curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sh - cloudtruth -V # Adds CloudTruth Values to build.env file to be passed with artifacts.reports.dotenv - cloudtruth --project MyFirstProject parameter export docker >> build.env - sed -i '/^$/d' build.env # Passes environment variables between stages artifacts: reports: dotenv: build.env Using CloudTruth Variables: stage: test script: - printenv dependencies: - "Install CloudTruth CLI" ``` {% hint style="danger" %} Take caution building environment variables that contain secret values as they can be exposed in your pipeline. Parameter export redacts secret values by default. {% endhint %} # Harness This walkthrough shows you how to pass CloudTruth parameters to Harness with a K8s operator. ## Prerequisites * You have a working knowledge of [Harness](https://ngdocs.harness.io/article/hv2758ro4e-learn-harness-key-concepts) and [K8s](https://kubernetes.io/docs/tutorials/kubernetes-basics/). * You have[ kubectl installed](https://kubernetes.io/docs/tasks/tools/#kubectl). * AWS CLI [configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API Access token](/org-management/access-control/access-tokens). ## Create Kubernetes Cluster The first step in the process is to deploy our Kubernetes cluster on our cloud provider. For this tutorial we are going to be using [Amazon EKS](https://aws.amazon.com/eks/), which is a managed container service. It would be fairly trivial to replicate these steps using another managed container service such as Google Kubernetes Engine (GKE) or Azure Kubernetes Service (AKS). If your cluster is already deployed, you can skip to "[Setting up Harness](#setting-up-harness)". ### Amazon EKS Cluster The easiest way to deploy an Amazon EKS cluster is using eksctl, a simple CLI tool for managing EKS clusters. The instructions for how to install or upgrade eksctl are [here](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html). However if another option is preferred, this [link](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html) gives details on how to deploy via eksctl, the AWS Management Console, or the AWS CLI. To deploy a cluster with eksctl in your default region you can execute the following: ``` eksctl create cluster \ --name YOUR-CLUSTER-NAME \ --version 1.21 \ --with-oidc \ --without-nodegroup ``` #### Create Nodes for EKS Cluster Once the EKS cluster is created, you must make sure there is a node group attached that can handle your workloads. Harness delegates require a minimum of [8Gb of memory](https://docs.harness.io/article/lwynqsgxt9-delegate-requirements-and-limitations#system_requirements) so we are using `tx.xlarge` nodes. If the basic eksctl command was used, the cluster is created by default without any node groups attached. To attach worker nodes, simply follow this [link](https://docs.aws.amazon.com/eks/latest/userguide/create-managed-node-group.html) that will walk you through the following commands. Create a key pair to allow access to the node group instances: ``` aws ec2 create-key-pair \ --key-name harness-key \ --query "KeyMaterial" \ --output text > harness-key.pem ``` Create a node group with the following command: ``` eksctl create nodegroup \ --cluster YOUR-CLUSTER-NAME \ --name delegate \ --node-type t3.xlarge \ --nodes 2 \ --nodes-min 1 \ --nodes-max 3 \ --ssh-access \ --ssh-public-key harness-key ``` {% hint style="warning" %} Note: If you used a method other than eksctl to spin up your EKS cluster, make sure your local kubectl points to your cluster, which can be done by [updating your kubeconfig](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html). {% endhint %} ## Setting up Harness Now that our cluster is up and running, it is time to set up Harness. The first step in doing so is [adding a harness delegate to our cluster](https://docs.harness.io/article/0hn6vdpeqz-install-kubernetes-delegate) with the Harness First Generation Community Edition. For EKS, this is as simple as [downloading the harness delegate yaml](https://docs.harness.io/article/0hn6vdpeqz-install-kubernetes-delegate#step_1_download_the_kubernetes_delegate) and applying it with: `kubectl apply -f harness-delegate.yaml` ![](/files/Oqbrd14PaLDiNKeNvmUO) Let's verify that our harness delegate is running by executing the command: `kubectl --namespace harness-delegate get pods` {% hint style="info" %} We can also verify this in the Harness GUI under Setup > Harness Delegates (right hand side menu) and checking that our delegate shows up with a "Connected" status. {% endhint %} #### Adding Cloud Provider and Helm Repository The next step is to [add our Kubernetes cluster cloud provider to Harness](https://docs.harness.io/article/l68rujg6mp-add-kubernetes-cluster-cloud-provider#step_1_add_the_cloud_provider). This is trivially easy to do when you inherit the authentications settings from the Harness delegate we installed in the previous step. To add a Cloud Provider, go to Setup > Cloud Providers > Add Cloud Provider > "Kubernetes Cluster". * Cluster Details: "Inherit from selected Delegate" * Delegate Selector: "eks-qqiuw-0" ![](/files/wPcnIL1vozpqsVCq98g3) We also need to add our KubeTruth Helm repository which is a K8s operator that continuously pulls CloudTruth parameters into ConfigMaps and Secrets in our Kubernetes cluster. Read more about KubeTruth [here](/configuration-management/integrations/kubernetes#kubetruth). To add the Helm repository, go to Setup > Connectors (on right hand menu) > Artifact Servers > "Add Artifact Server". * Type: Helm Repository * Name: "KubeTruthHelm" * Repository URL: "" ![](/files/oXcciwjqZKarQTnKPy05) #### Adding a new Application and Service To add a new application navigate to Setup > "Add Application", and give it whatever name you like, "KubeTruthDemo" in our case. Once we create the application, we must add a service to it. Navigate to Services > "Add Service". Provide the service a name ("DemoService" in our case), and the deployment type must be "Kubernetes". On the service overview page click on the 3 dots in the upper right corner of "Manifests" and select the option that says "Link Remote Manifests". ![](/files/MIAn1QZx9DKFWr0FiQT4) Provide the following details and submit the services remote manifest: * Manifest Format: Helm Chart from Helm Repository * Helm Repository: KubetruthHelm (that we set up earlier) * Chart Name: "kubetruth" (case sensitive) * Helm Version: v3 (or v2 if you prefer to use that) On the service overview page, scroll down to "Values YAML Override" and click "Add Values". Choose the option "inline", here you are going to want to add the [CloudTruth API key](/org-management/access-control/access-tokens#creating-an-api-access-token) you created as a prerequisite, the YAML is as follows: ``` appSettings: apiKey: YOUR_CLOUDTRUTH_API_KEY ``` {% hint style="info" %} Optionally, we can also add a CloudTruth environment using the `appSettings.environment`key, but since we created our parameters in the "default" CloudTruth environment we can omit that key. {% endhint %} #### Adding an Environment The next step is to set up an environment on Harness to do our deployment. Navigate to Setup > Our App (KubetruthDemo) > Environments > "Add Environment". Provide a name, we will call it "DemoEnv". You can either select Production or Non-Production for Environment Type, we will create a Production for the purposes of this tutorial. Once the environment is created, we need to add an infrastructure definition for it. On the Environment Overview page click "Add Infrastructure Definition" and provide the following details. * Name: "EKSCluster" * Cloud Provider Type: Kubernetes Cluster * Deployment Type: Kubernetes * Select bubble for "Use Already Provisioned Infrastructure" * Cloud Provider: Kubernetes Cluster * Namespace is fine as "default" * Release Name: keep default ![](/files/o2jwdZXFC6b50Xu06e3O) #### Creating Deployment Workflow It is time to create a deployment workflow, for this navigate to Setup > Our App (Kubetruth Demo) > Workflows > "Add Workflow" and provide the following details. * Name: "RollingWorkflow" * Workflow Type: Rolling Deployment * Environment: DemoEnv (created in earlier step) * Service: DemoService (created in earlier step) * Infrastructure Definition: EKSCluster (created in earlier step) ![](/files/osTdlO63Ygw8BSegSci5) From the Workflow Overview, we need to add a pre-deploy step to apply our KubeTruth CRD. Under the "Deploy" section click "Add Step" . Navigate to Utility > Shell Script. ![](/files/mNcauL9fc4V8WBGdU3YM) Provide the following step details: * Name: "Shell Script" * Script Type: BASH * Script: ``` kubectl apply -f <(curl --silent https://raw.githubusercontent.com/cloudtruth/kubetruth/main/helm/kubetruth/crds/projectmapping.yaml) ``` {% hint style="danger" %} **Important:** Make sure to hit the little up arrow to the direct right of "Shell Script" under the "Deploy" section, since we want it to execute *before* the rollout deployment. {% endhint %} ![](/files/ETet6CYJVJTeHB8fMPZc) {% hint style="info" %} If done as a canary or blue/green deployment, make sure the shell script is entered as a "Pre-Deployment" step, since it needs to execute before the actual deployment (or else the CRD will not exist). {% endhint %} Now you can hit "Deploy" on the upper right (then "Submit")! #### Verifying our Deployment To verify that our KubeTruth deployment was successful and that our demo CloudTruth parameters are in our Kubernetes cluster, we need to look at the ConfigMap and for the "default" Kubernetes namespace (or whatever namespace you deployed to). The easiest way to do this is to navigate to your terminal and list all of your configmaps. You will see that you now have configmaps created from your CloudTruth Projects. `kubectl get configmap -A` Describe details from a specific configmap created from your workflow: `kubectl describe configmap "generated-configmap-name"` To check the value of a specific key, run: ``` kubectl get configmap "generated-configmap-name" -o jsonpath='{.data.KEY_NAME}' ``` If you want to verify the rolling updates to the ConfigMap, try changing a parameter value in CloudTruth and checking for the updated value using kubectl after a minute or two. {% hint style="success" %} You have successfully deployed a Kubernetes operator that dynamically generates and updates configmaps and secrets! To clean up your AWS clusters you can run the following: eksctl delete nodegroup NODEGROUPNAME \_--\_cluster \_\_ YOUR-CLUSTER-NAME aws ec2 delete-key-pair --key-name KEY\_NAME eksctl delete cluster YOUR-CLUSTER-NAME {% endhint %} # Jenkins This walkthrough will guide you through using Jenkins with CloudTruth enabling you to manage your multiple environments parameters and secrets from a centralized location. ## Prerequisites * You have created one or more [CloudTruth Parameters](https://github.com/cloudtruth/ctdocs/blob/live/integrations/broken-reference/README.md). * You have created a [CloudTruth API Access token](https://github.com/cloudtruth/ctdocs/blob/live/integrations/broken-reference/README.md). * Working knowledge of [Jenkins](https://www.jenkins.io/doc/book/installing/). * [Docker](https://docs.docker.com/) installed ## Install Jenkins with a Dockerfile This example will install Jenkins as a [Docker image](https://www.jenkins.io/doc/book/installing/docker/) based on the official Jenkins guide. The Dockerfile will be customized to install the [CloudTruth CLI ](/configuration-management/cli-and-api/cloudtruth-cli#installation)in the official [Jenkins image](https://hub.docker.com/r/jenkins/jenkins/). Secrets and variables will be passed directly into Jenkins pipelines with the CloudTruth CLI. Create a [bridge network](https://docs.docker.com/network/bridge/) in Docker using the following command: ``` docker network create jenkins ``` Customize the official Jenkins Docker image: ``` FROM jenkins/jenkins:2.303.2-jdk11 USER root RUN apt-get update && apt-get install -y apt-transport-https \ ca-certificates curl gnupg2 \ software-properties-common RUN curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add - RUN apt-key fingerprint 0EBFCD88 RUN add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/debian \ $(lsb_release -cs) stable" RUN apt-get update && apt-get install -y docker-ce-cli # Install the CloudTruth CLI RUN (curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh || wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh) | sh USER jenkins RUN jenkins-plugin-cli --plugins "blueocean:1.25.0 docker-workflow:1.26" ``` Build a new docker image from this dockerfile: ``` docker build -t jenkins-cloudtruth:1 . ``` Run the customized image: ``` docker run --name jenkins-blueocean --rm --detach \ --network jenkins --env DOCKER_HOST=tcp://docker:2376 \ --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 \ --publish 8080:8080 --publish 50000:50000 \ --volume jenkins-data:/var/jenkins_home \ --volume jenkins-docker-certs:/certs/client:ro \ jenkins-cloudtruth:1 ``` Obtain the admin password for your deploy once the container is running: ``` sudo docker exec jenkins-blueocean cat /var/jenkins_home/secrets/initialAdminPassword ``` Navigate to [http://localhost:8080](http://localhost:8080/) to login and customize Jenkins with a username of `admin` and the password you obtained from the previous step. You can Install Suggested plugins from this screen to complete setup and skip the rest of the configuration. ## Provide Jenkins Access to CloudTruth Adding a [Jenkins global credential](https://www.jenkins.io/doc/book/using/using-credentials/#adding-new-global-credentials) for the CloudTruth API key allows a Jenkins pipeline to securely access parameters and secrets stored in CloudTruth. Navigate to Dashboard -> Manage Credentials -> Jenkins store -> Global credentials -> Add: Select the Credential Kind as `Secret text`. Fill in the **Secret** field with a [generated CloudTruth API Access token](/org-management/access-control/access-tokens) as a Jenkins Global Credential. Add a description which is used to reference the key in the pipeline then click OK. ![](/files/nyoClooruvGl8umBaiMn) ## Configure a Jenkins Pipeline with CloudTruth #### Create a new pipeline From the Jenkins dashboard select `New Item`. Provide a name, select pipeline and hit OK: ![](/files/EWKUSIkUL8oonnhcWEKI) #### Configure the CloudTruth API Key as a pipeline parameter Select `This project is parameterized` and add a [`Credentials Parameter`](https://www.jenkins.io/doc/book/using/using-credentials/). ![](/files/giwJ3Klgj8qis4GOtqaj) Provide the parameter Name as `CLOUDTRUTH_API_KEY`. The CloudTruth CLI uses this variable to pull secrets and parameters from CloudTruth. Select Default value as the [Global Credential](#provide-jenkins-access-to-cloudtruth) we created as the value for `CLOUDTRUTH_API_KEY` and mark the parameter as required. ![](/files/EAWVzMM7Me9O6iZqrPyg) #### Create pipeline environment variables from CloudTruth Add the following pipeline script and click Save: ``` pipeline { environment { CLOUDTRUTH_API_KEY = credentials('CLOUDTRUTH_API_KEY') CLOUDTRUTH_PARAMETER = sh(script:'cloudtruth --project MyFirstProject --env default parameters get jenkins', returnStdout: true).trim() } agent any stages { stage('CloudTruth') { steps { echo "Retrieve Parameter from CloudTruth: ${env.CLOUDTRUTH_PARAMETER}" } } } } ``` This groovy script sets the `CLOUDTRUTH_API_KEY` using the Jenkins [credential](https://www.jenkins.io/doc/book/using/using-credentials/) value we specified as a pipeline parameter. It then populates an environment variable `CLOUDTRUTH_PARAMETER` with a sh script that calls the CLI. This allows variables to be used in downstream stages. You can update the CLI command with your own parameter or create a parameter named `jenkins` in `MyFirstProject`. You can use these CLI commands to set the variables used in this example: ``` cloudtruth --project MyFirstProject parameter set jenkins -v pipeline cloudtruth --project MyFirstProject parameter set secret -v masked --secret true ``` {% hint style="info" %} The environment variable for CLI access in the pipeline script must be named: `CLOUDTRUTH_API_KEY` {% endhint %} ![](/files/nMrW9cTo0BC5cxEMJQ39) #### Build pipeline with parameters From the pipeline click `Build with Parameters` and select `CloudTruth API Key` then click Build. ![](/files/bjUMpMmzG0VTpKOlXdTn) From the build page view the Console Output. The parameter value `pipeline` is successfully set and echoed in our pipeline stage! ![](/files/b8rpji51ui40M71BkGh4) ### Masking external secrets in a Jenkins Pipeline Jenkins will automatically mask built in [credentials parameters](https://www.jenkins.io/doc/book/using/using-credentials/) like the CloudTruth API key. When using external secret stores we will call the [Mask Passwords](https://plugins.jenkins.io/mask-passwords/) plugin. From the Plugin Manager search for Mask Passwords. Select the plugin and Install with a restart of Jenkins. ![](/files/KMuuTWM3wqhbia9mMVWe) We can now use the `MaskPasswordsBuildWrapper` and `withEnv` to wrap the CloudTruth secret returned from our CLI call. The pipeline is built with the CloudTruth API key as described in [configuring a Jenkins pipeline](#configure-a-jenkins-pipeline-with-cloudtruth). We set a variable from a CloudTruth parameter called `secret` . The following groovy is an example pipeline script that sets a masked environment variable using the plugin wrapper. ``` pipeline { environment { CLOUDTRUTH_API_KEY = credentials('CLOUDTRUTH_API_KEY') } agent any stages { stage('CloudTruth') { steps { script{ CLOUDTRUTH_SECRET = sh(script:'cloudtruth --project MyFirstProject --env default parameters get secret', returnStdout: true).trim() wrap([$class: 'MaskPasswordsBuildWrapper', varPasswordPairs: [[password: CLOUDTRUTH_SECRET]]]) { withEnv(["SECRET=${CLOUDTRUTH_SECRET}"]){ sh 'echo Retrieve Secret from CloudTruth: $SECRET' sh 'printenv' } } } } } } } ``` As a result when viewing the console output the secret is masked in the echo. It is also masked when viewing an export of the current environment variables for the step. ![](/files/ZvrwKyHcQhvRvtToVd0x) With this technique the secrets are also masked in Blue Ocean build details. ![](/files/yGDSWxjftiTxMjmp9WQI) # Kubernetes K8s This walkthrough shows you how to use various methods of passing CloudTruth parameters to K8s as [ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) and [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/). You also still have the option of using the [CloudTruth CLI directly in your container](https://docs.cloudtruth.com/integrations/docker) pods. * Creating K8s Secrets * Creating K8s ConfigMaps * KubeTruth automated K8s config management ## Prerequisites * You have a working knowledge of K8s. * You have[ kubectl installed](https://kubernetes.io/docs/tasks/tools/#kubectl). * You have created one or more [CloudTruth Parameters](/configuration-management/parameters/parameter-management/managing-parameters). * You have created a [CloudTruth API Access token](/configuration-management/integrations#api-tokens). ## K8s Secrets [Kubernetes secrets](https://kubernetes.io/docs/concepts/configuration/secret/) store your sensitive information such as your CloudTruth API key or any secrets required by your specific app. You can [manage K8s secrets](https://kubernetes.io/docs/tasks/configmap-secret/) multiple ways. **Create a CLOUDTRUTH\_API\_KEY secret** The \*\*\*\* `kubectl create secret` command will create a base64 encoded K8s secret. You can directly provide `CLOUDTRUTH_API_KEY="YOUR_TOKEN"` as a literal to use in your pods with the CloudTruth CLI. ``` kubectl create secret generic cloudtruth-access --from-literal=CLOUDTRUTH_API_KEY="YOUR_TOKEN" ``` You can also store your secrets in CloudTruth and pass them directly to kubectl with the CloudTruth CLI. Here we have a parameter `CLOUDTRUTH_API_KEY`created in CloudTruth and use the following cli command to retrieve and pass the value in one step. ``` kubectl create secret generic cloudtruth-access --from-literal=CLOUDTRUTH_API_KEY=`(cloudtruth --project MyFirstProject parameter get CLOUDTRUTH_API_KEY)` ``` You can also create K8s secrets by applying a yaml secret file. The secret must be base64 encoded in the yaml file itself. ``` apiVersion: v1 kind: Secret type: Opaque metadata: name: my-secrets data: CLOUDTRUTH_API_KEY: ZjAwbDNkeTB1 MY_PASSWORD: c3VwZXJzZWNyZXRwYXNzd29yZA== ``` K8s Secrets can then be accessed in standard ways. You can access your CloudTruth API key as an environment variable inside your Deployment yaml with [`envFrom`](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-as-container-environment-variables). ``` spec: containers: - name: secrets-example image: my-container-image envFrom: - secretRef: name: my-secrets ``` {% hint style="warning" %} Review the K8s [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) docs for details on how secrets are stored as unencrypted base64-encoded strings. {% endhint %} ## K8s ConfigMaps [Kubernetes ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) allow you to store non secret type data in key-value pairs that can be consumed by pods in various ways. ConfigMaps can be built from parameters managed directly in CloudTruth providing you flexibility to build out a hierarchy of K8s projects and environments with unique keys and values. Once your ConfigMap parameters are added to CloudTruth, create a CloudTruth ConfigMap template. This is an example CloudTruth template for a flask application ConfigMap. CloudTruth will automatically populate values based on your specified environment. ``` kind: ConfigMap apiVersion: v1 metadata: name: flask-configmap data: FLASK_APP: {{FLASK_APP}} FLASK_ENV: {{FLASK_ENV}} FLASK_MESSAGE: {{FLASK_MESSAGE}} FLASK_RUN_HOST: "{{FLASK_RUN_HOST}}" FLASK_RUN_PORT: "{{FLASK_RUN_PORT}}" ``` Now you can easily create ConfigMaps across your customized projects and environments. This will directly apply a ConfigMap by using the CloudTruth cli to dynamically generate parameters from a template `flask-configmap` in project `Flask`. ``` kubectl apply -f <(cloudtruth --project Flask templates get flask-configmap) ``` Alternatively you can also use CloudTruth templates to generate yaml files for your configmaps. ``` cloudtruth --project Flask templates get flask-configmap > flask-configmap.yaml ``` ## KubeTruth With the ever growing number of services, managing a K8s deployment brings continuously expanding configuration complexity. KubeTruth integrates with CloudTruth providing you an automated K8s configuration management system. KubeTruth is designed to dynamically build and update K8s ConfigMaps and Secrets while providing you centralized control over your data across a sprawling combination of projects and environments. ![](/files/-Me_l_GyzErM5aHMVx2A) You can get started by adding the CloudTruth repo to Helm. ``` helm repo add cloudtruth https://packages.cloudtruth.com/charts ``` You can now use helm to install KubeTruth in a dedicated namespace `demokubetruth`. Provide your CloudTruth [API Key](/org-management/access-control/access-tokens#creating-an-api-access-token) and the targeted CloudTruth [environment](/configuration-management/environments). ``` helm install \ --create-namespace --namespace demokubetruth \ --set appSettings.apiKey= \ --set appSettings.environment= \ kubetruth-install cloudtruth/kubetruth ``` Once installed KubeTruth will create ConfigMaps and Secrets for each CloudTruth project. It will dynamically poll CloudTruth and update any changes directly within K8s! This provides you a centralized management source for your pods configuration values. ConfigMaps and Secrets managed by KubeTruth get created with a label: `app.kubernetes.io/managed-by: kubetruth` You can find KubeTruth created resources with the -l option. ``` kubectl get configmaps -l app.kubernetes.io/managed-by=kubetruth -A ``` ``` kubectl get secrets -l app.kubernetes.io/managed-by=kubetruth -A ``` ### Customizing KubeTruth Project requirements differ so KubeTruth allows customization with a [`Project Mapping`](https://github.com/cloudtruth/kubetruth/blob/master/helm/kubetruth/crds/projectmapping.yaml) Custom Resource Definition. This allows you to [manage resources](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#in-place-updates-of-resources) with standard K8s practices. Here are some common use case examples of configuring the root installation and working with the CRD overrides. #### **Deploy CloudTruth projects to dedicated namespaces** Patch `projectMappings.root.spec.context.resource_namespace` to create a namespace per CloudTruth project. ``` kubectl patch projectmapping kubetruth-install-root -n demokubetruth --type json --patch '[{"op": "replace", "path": "/spec/context/resource_namespace", "value": "{{ project | dns_safe }}"}]' ``` **Inheriting parameters from a base project** If you have a common set of parameters that you would like to be present in all of your ConfigMaps and Secrets you can specify a project to import it's parameters across other projects. You can patch `projectMappings.root.spec.included_projects` which will import all Parameters from a CloudTruth project named `base` into our other configmaps and secrets. ``` kubectl patch projectmapping kubetruth-install-root -n demokubetruth --type json --patch '[{"op": "replace", "path": "/spec/included_projects", "value": ["base"]}]' ``` {% hint style="info" %} Inheritance is non-recursive. If project A imports B and B imports C, then A will only get B's parameters. For key conflicts, if project A includes \[B, C], then the precedence is A overrides C overrides B. {% endhint %} #### Override spec You can create a `kind: ProjectMapping` with an override scope for customization of naming conventions and key filters. This allows you to create custom configmaps and secrets that do not have to follow the exact project layout in CloudTruth. ``` kubectl apply -n demokubetruth -f - < instance_name = "CloudTruth-development" instance_type = "t2.micro" zone = "us-west-2a" s3_bucket_name = "cloudtruth-grunt-free-panda" s3_tag_name = "CloudTruth-development" ``` You can change to the production or staging directories and pass the respective CloudTruth environment to deploy various settings across your different infrastructure! #### Cleanup Destroy the AWS resources by passing environment variables the same way we created them. ``` cloudtruth --project Terragrunt --env development run -- terragrunt run-all destroy ``` You can see the source code for the Terraform modules and Terragrunt Deploy in the following repos. {% embed url="" %} {% embed url="" %} # Explorer The CloudTruth explorer provides you a simple way of verifying the health and content of all your integrations in one place. Navigate to the Explorer page from the [CloudTruth App](https://app.cloudtruth.com/) integrations page. The Location windows will show the integration paths that have been added in your account. In this example the explorer is showing integrations for AWS and GitHub. ![](/files/-Mi8PwtAD3J7ke6buAT0) Selecting the AWS integration will bring up the integrations for AWS. ![](/files/HQdRZlFZVYCHfR2FKmhC) You can continue through each integration to see the values that are available to use with[ External Parameter Values](/configuration-management/parameters/parameter-management/external-values). The reference location will display the full path tree to the selected integration. ![](/files/pp6nTW9Bbd9Zu4ssAo04) # Circle CI Describes how to integrate CloudTruth with Circle CI ## Integrating CloudTruth with CircleCI to Inject Configuration Variables and Secrets This documentation covers integrating CloudTruth with CircleCI to inject configuration variables and secrets directly into your CircleCI pipelines using the CloudTruth CLI. ### Overview By integrating CloudTruth with CircleCI, you can securely manage and inject configuration variables, environment-specific settings, and secrets into your CircleCI pipelines. This enables consistent, secure, and flexible configuration management across different environments. ### Prerequisites 1. **CloudTruth Account**: Ensure you have an active CloudTruth account. Visit [CloudTruth](https://cloudtruth.com) to sign up. 2. **CloudTruth CLI**: The CloudTruth CLI should be installed and accessible in your CircleCI pipeline. 3. **API Key**: Generate a CloudTruth API key to authenticate within CircleCI. This key allows CircleCI to access and inject the variables and secrets from CloudTruth into the pipeline. ### Step 1: Set Up CloudTruth API Key in CircleCI 1. Go to your CircleCI project’s settings. 2. In the left-hand sidebar, click **Environment Variables**. 3. Add a new environment variable: * **Name**: `CLOUDTRUTH_API_KEY` * **Value**: Your CloudTruth API key (obtained from your CloudTruth account under API settings). This will allow CircleCI to authenticate with CloudTruth using the CLI during pipeline execution. ### Step 2: Modify Your CircleCI Configuration In your project repository, modify your `.circleci/config.yml` to install the CloudTruth CLI and use it to fetch configuration data or secrets. Here’s a sample configuration that demonstrates how to integrate CloudTruth in a CircleCI pipeline: ```yaml version: 2.1 executors: default-executor: docker: - image: circleci/python:3.8 jobs: build: executor: default-executor steps: - checkout - run: name: Install CloudTruth CLI command: | curl -Ls https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | bash - run: name: Authenticate CloudTruth command: | export CLOUDTRUTH_API_KEY=${CLOUDTRUTH_API_KEY} cloudtruth --api-key ${CLOUDTRUTH_API_KEY} status - run: name: Fetch CloudTruth Configuration command: | # Fetching configuration variables and secrets from CloudTruth cloudtruth parameters get --project my_project --env production --format env > .env source .env - run: name: Use CloudTruth Variables in Pipeline command: | # Example usage of CloudTruth configuration variables in the build process echo "API_KEY: ${API_KEY}" echo "ENVIRONMENT: ${ENVIRONMENT}" # Your build commands go here ./deploy.sh workflows: version: 2 build: jobs: - build ``` #### Key Steps Explained: 1. **Install CloudTruth CLI**: This step installs the latest version of the CloudTruth CLI in the CircleCI build environment. 2. **Authenticate CloudTruth**: This step authenticates CloudTruth using the API key stored in CircleCI environment variables. 3. **Fetch Configuration**: The `cloudtruth parameters get` command retrieves the configuration variables and secrets from CloudTruth. The `--format env` flag outputs the parameters in a format compatible with environment variables, which can then be sourced into the pipeline. 4. **Use Configuration Variables**: The variables fetched from CloudTruth can be referenced using standard environment variable syntax in subsequent pipeline steps. ### Step 3: Fetch Specific Parameters Using the flag, you can also specify particular variables and secrets you want to inject into your pipeline. For example: ```bash cloudtruth parameters get --name API_KEY --project my_project --env production ``` This will retrieve only the `API_KEY` from the `production` environment in the `my_project` project. ### Best Practices * **Scope by Project and Environment**: Always scope your configuration variables by project and environment to ensure you retrieve the correct data for each deployment stage. * **Use Secrets Management**: CloudTruth allows you to manage secrets like API keys, database passwords, and tokens. These can be securely injected into your CircleCI pipelines, minimizing the risk of exposing sensitive information. * **Version Control**: CloudTruth provides versioning of configuration parameters, allowing you to easily roll back to previous versions or track changes over time. ### Example Use Cases * **Managing API Keys**: Store API keys for different services in CloudTruth and inject them into your CircleCI pipelines based on the environment (e.g., staging, production). * **Environment-Specific Configurations**: Use CloudTruth to store environment-specific configurations (e.g., database URLs, feature flags) and dynamically fetch them based on the current environment. *** With this integration, you can securely and dynamically manage your configuration variables and secrets in CloudTruth while ensuring they are automatically injected into CircleCI pipelines. This streamlines your CI/CD process and reduces the complexity of managing sensitive configuration data. # Events, Notifications, Webhooks Get notified when a change is made. CloudTruth allows you to subscribe to events. Use the example code below to configure sending a notification to a Slack channel. POST to `/api/v1/webhooks/` with a payload ``` { "name": "MyNewWebhook", "event_types": [ "parameter_created" ], "type": "slack", "configuration": { "token": "string", "channel": "string", "username": "string" }, "organization": "string" } ``` `organization` is the organization ID for the installing org. I don't know how to advise a user to get this info and we might want to remove it from the request and just infer it in the same way we usually do. `event_types` can be a list containing any combination of these items: ``` "parameter_created" "parameter_updated" "parameter_deleted" "project_created" "project_updated" "project_deleted" "environment_created" "environment_updated" "environment_deleted" "value_created" "value_updated" "value_deleted" ``` `type` can only be slack, until we implement a different event handler `configuration` is a JSON field that requires three keys (these are service-specific, this example is only for Slack): ``` { "token": , "channel": , "username": , } ``` To generate a Slack API token: 1. Go to 2. Click "Create New App" 3. Select "From a manifest" 4. Paste in the provided manifest (below) 5. Click "Create" 6. Click "OAuth & Permissions" on the left nav 7. Click the "Install to " button 8. Copy the generated Bot User OAuth Token Slack App Manifest: ``` { "display_information": { "name": "CloudTruth Webhook" }, "features": { "bot_user": { "display_name": "CloudTruth Webhook", "always_online": false } }, "oauth_config": { "scopes": { "bot": [ "chat:write.public", "chat:write" ] } }, "settings": { "org_deploy_enabled": false, "socket_mode_enabled": false, "token_rotation_enabled": false } } ``` # Types Manage type checking parameter values with rules and ranges. Use the Type feature for guardrails, policy enforcement and eliminating misconfigurations. Managing Types requires Contributor or Admin permissions. Select **Types** under the **Admin** menu to open the screen below. (First-time customers will see an empty screen.)

Example of a populated list of Types.

1. List of base types and what they do. Boolean: Can be used directly for parameters or as a parent for custom types. Automatically includes permutations such as Yes, No, True, False. Enum: Must be used as a parent for custom types. Create lists that scope the selection to only approved values. Integer: This can be used directly for parameters or as a parent for custom types. String: This can be used directly for parameters or as a parent for custom types. The string type is the base type for regular expressions (Regex). 2. An example of a type rule that uses a regex to validate an AWS Region is correctly formatted.

Sample regular expression.

3. An example of an enum list to validate a parameter value is correct.

Sample list of enums for the type "AWS Regions List".

Use the UI for short enum lists or the API to bulk-add longer list items. Copy the code below and replace the API\_KEY value with an API key for your organization with Contributor or Admin permissions. ``` #!/bin/bash API_KEY="YOUR-API-KEY" usage() { echo "Usage: $0 [-n ] [-r ]" 1>&2; exit 1; } while getopts ":n:d:r:" o; do case "${o}" in n) enum_name=${OPTARG} ;; d) enum_desc=${OPTARG} ;; r) constraints=${OPTARG} ;; *) usage ;; esac done shift $((OPTIND-1)) if [ -z "${enum_name}" ] || [ -z "${constraints}" ] || [ "${API_KEY}" == "fill-me-in" ] then usage fi data_str='{"name":"'${enum_name}'","description":"'${enum_desc}'","parent":"https://api.cloudtruth.io/api/v1/types/1b606a2f-197d-4173-a588-70c12c8b794d/"}' response=$(curl -X POST 'https://api.cloudtruth.io/api/v1/types/' -H 'content-type: application/json' -H 'authorization: Api-Key '"${API_KEY}" --data-raw "${data_str}") echo "${response}" type_id=`echo "${response}" | jq -r '.id'` echo "Type ID: ${type_id}" curl -X POST 'https://api.cloudtruth.io/api/v1/types/'"${type_id}"'/rules/' \ -H 'authorization: Api-Key '"${API_KEY}" \ -H 'content-type: application/json' \ --data-raw '{"type":"one_of","constraints":'"${constraints}"',"typeId":"'"${type_id}"'"}' ``` Sample command line for the script (assumes the script file is named "create\_enum.sh"): -n Type name (should be short) -d Description -r List items. Use quote comma-separated structure ``` ./create_enum.sh -n "Fetch Interval" -d "Interval to trigger a fetch." -r '["daily", "weekly", "monthly"]' ``` # Compare Compare parameter values between environments CloudTruth has the ability to compare value between two or more environments. This is useful when needing to view parameter values side-by-side and more specifically visualize those parameter values which differ between environments (overridden). This is also useful in troubleshooting when a particular environment isn't working as expected, seeing the environment value differences can help quickly determine expected vs. unexpected values. ## Comparing environment values * Open the parameter value comparison view by expanding Reports, via the left-hand navigation menu, and clicking the Compare option. * Based on the currently selected project shown in the global project selector, the project's parameter list table :
* From here, we can add/ remove environments to compare via the `ENVIRONMENT VALUES FOR` multi-selector:
* Adding or removing environments from the field will change the comparison table results as needed:
* Several convenience filters have been added to better visualize and filter down to the precise data: * Show Secrets - reveal the value of all secret parameters on displayed * Show Differences - filter out all parameters where the values are identical, showing only those parameters where the values are different * Show Inherited - when comparing parameters in a child project we can also display those parameters inherited from the parent project {% hint style="info" %} This page, while mainly used to compare values between environments, is also similar to the Parameter List table where values can be edited, secrets revealed, and overrides removed. {% endhint %} # History Go back in time to see historical parameter values CloudTruth allows users to see a project's historical parameter or template values on demand. These values can be visualized by entering a date-time stamp or environment tag (effectively a date-time stamp). ## Parameter History * To open the parameter value history view, expand Reports via the left-hand navigation menu and click the History option. * The project's parameter list table will be displayed based on the currently selected project and environment shown in the global project selector. Here, we have selected `MyFirstProject` and the `production` environment:
Once the page has been accessed we can now view the history by either selecting a date and time or choosing an [existing environment tag](/configuration-management/environments). ### Viewing by date and time * Clicking in the `Select date` field will open a date-time picker or the date and time can be entered manually following the `YYYY-MM-DD hh:mm:ss` format
* Clicking `OK` then `Apply` will submit the data and retrieve the historical values. The image below shows `param_2` was modified (overridden) after the selected date:
### Viewing by Tag [Environment Tags](/configuration-management/environments) represent a date and time stamp with the added convenience of being identified by name. We've already created an environment tag representing the same date and time we selected when viewing by date and time in the previous section. * Select the existing environment tag then click `Apply` to submit the tag and retrieve the historical values. As above, the image below shows `param_2` was modified (overridden) after the set date within the environment tag:
## Template History In the example above we demonstrated how to view the historical differences between a project's parameter values. We can also view the historical differences between a project's templates. Choosing the environment tag or selecting a date and time stamp is the same, but the view needs to change. In this example we will check the project's `default` environment and an environment tag to see the template differences. * Select the `Templates` option to change to the template view:
* Select the existing environment tag then click `Apply` to submit the tag and retrieve the historical values and list any existing templates:
* Click the `Show differences` expander to view the differences between the current and tagged template versions (in this case we only have a single template available):
# Expirations Track parameter, secret, cert, API expirations and automated rotations CloudTruth lets users see track parameter and secret expiration and rotation. These values can be visualized by entering a date-time stamp or environment tag (effectively a date-time stamp). ## Parameter Expiration * To open the parameter expiration view, expand Reports via the left-hand navigation menu and click the Expiration option. * The project's parameter list table will be displayed based on the currently selected project and environment shown in the global project selector. Here, we have selected `MyFirstProject` and the `production` environment: # PRODUCT # What is CloudTruth? ## **Increase shipping velocity by > 70%.** ## **Your new config command center is ready.** ### **Explore simple integration to your existing release pipeline.** {% embed url="" %} ### Manage IaC / Terraform input variables for multiple environments. {% embed url="" %} ### **Automate dev handoffs to ops for consistently reliable deployments** {% embed url="" %} \
# Interactive Demo ## 5-minute clickable overview of the web app and CLI. {% embed url="" %} # Kubernetes Automatically create and update ConfigMaps, Secrets, Helm Charts, or any CRD. ## Kubernetes Configuration Management System CloudTruth’s open-source Kube operator is the easiest way to manage your Kube config and create a self-service developer experience. ### Manage ConfigMaps and Secrets * Use CloudTruth's [open-source Kubernetes operator](https://github.com/cloudtruth/kubetruth) * Self-serve Kubernetes ConfigMap platform * Easily distribute and rotate Kubernetes Secrets {% embed url="" %} ## Kubernetes Operator ### Automatically Sync ConfigMaps and Secrets with Kubetruth
It’s time to leave tedious, manual Kubernetes management in the past. Centralize your configuration management and eliminate manual YAML file editing with CloudTruth. {% embed url="" %} # Terraform Manage the inputs and outputs for Terraform, CloudFormation, Pulumi, AWS CDK or any other Infrastructure as Code tools. ## Generate Perfect Config for IaC
### Master your input variables. One of the most challenging DevOps tasks is getting config and secrets "just right" for every component in your system. Whether that's config for infrastructure or applications, generating a consistently perfect config file is a real challenge. This video uses CloudTruth to simplify deploying to dynamic AWS environments. {% embed url="" %} ### Create templated .tfvars for all environments. Manage Terraform variables from a rich UI or CLI. Inject .tfvars at deploy time to increase release velocity. {% embed url="" %} ### Get up and running quickly with the Terraform provider. Provision CloudTruth with the [open-source Terraform Provider](https://github.com/cloudtruth/terraform-provider-cloudtruth).

https://github.com/cloudtruth/terraform-provider-cloudtruth

# CI/CD Pipeline Configuration Inject the most accurate config at the perfect time into CI/CD pipelines. No more leaking secrets into log files. Works with all DevOps CI CD pipelines and Infrastructure as Code tools.
### Create Trusted Templated Config at all Pipeline Stages * Use CloudTruth's [open-source clients](https://github.com/cloudtruth/) to format config for any CI/CD pipelines, including Jenkins, CircleCI, ArgoCD, GitHub Actions, and Bitbucket Pipelines. * Inject secrets and config into GitLab CI CD pipelines. * No more manually editing YAML files. {% embed url="" %} {% embed url="" %} # Cloud CMDB Generate perfect consistent config for every deployment AND automatically track all config changes across build, deploy, and runtime workflows. ### The Proactive Cloud CMDB * Connects to all configuration sources, including AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, Git repos, and cloud buckets. * Aggregates all changes into an immutable audit trail. * Share and collaborate on config with robust RBAC, SSO, and 3rd party integrations. {% embed url="" %} # Secrets Management Securely track, sync and share passwords, API keys, SSH keys, and certificates with robust role-based access controls to protect sensitive data. ## Centralized Secrets Management One place to manage passwords, API keys, certificates, secret rotation, and other sensitive data to inject secrets into the build, deploy, and run-time pipelines. ### A better way to manage secrets. Learn how CloudTruth helps decouple secrets management and parameter settings from consumption. {% embed url="" %} ### Fix leaked secrets and easy rotations.
# GitOps Inject perfect config into GitOps workflows. CloudTruth is the easiest way to drive configuration and automation with all CI/CD. ## Better GitOps = No ClickOps
### Trusted templated config for all pipeline stages * Use CloudTruth's [open-source clients](https://github.com/cloudtruth/) to format config for any CI/CD pipelines, including Jenkins, CircleCI, ArgoCD, GitHub Actions, and Bitbucket Pipelines. * Inject secrets and config into GitOps pipelines. * No more manually editing YAML files. {% embed url="" %} {% embed url="" %} # Our Manifesto One of the primary goals of CloudTruth is to allow you to decouple the management of your configuration from its consumption. Enhance your developer experience by automatically generating perfect, consistent configurations for every deployment. ## Today's Cloud Needs Centralized Configuration Management The rise of microservices, Kubernetes, GitOps, and serverless means configuration is becoming distributed, decentralized, and “pushed to the edge.” It's time to simplify and organize your config data to meet security, reliability, and velocity goals.
### Executive Summary * Cloud and application configuration is becoming a shared responsibility between DevOps and engineers. This increases speed and innovation. * The unfortunate downside is increased configuration complexity, pressures on customization, and organizational and process misalignment. * Three approaches to ameliorate this complexity are reviewing existing configuration integrations, cross-team training and awareness, and new solutions to improve visibility across the newly distributed and decentralized world of cloud configuration. * A centralized platform gives you a configuration control management plan and helps avoid misconfigurations in application deployment. ### What We'll Cover Containers, Kubernetes, serverless, and infrastructure as code (IaC) techniques are changing how modern cloud systems are configured. Applications and their components are becoming self-contained, with substantial infrastructure configuration embedded inside their source repositories. In addition, system configuration is becoming decentralized and distributed, which substantially increases the difficulty of managing the cross-cutting concerns of security, compliance, and reliability. And when these self-contained components become inconsistent across time – from development to testing to staging to production – the complexity increases. > **Methodology** > > **CloudTuth interviewed five hundred IT professionals across roles ranging from CTO, CIO, VP Eng, DevOps, CISO and SecOps to research.** ### Cloud Configuration Challenges **Keeping Up with Innovation** As millions of people adjust to working virtually, software-as-a-service (SaaS) applications and the public cloud infrastructure they rely on have expanded overnight to keep up with increased online activity. As a result, application developers are under even more pressure to bring new multi-cloud applications and advanced versions of existing ones to market quickly. However, application development tools are also advancing quickly. Applications and components are becoming self-contained, with substantial infrastructure configuration embedded inside their source repositories. As a result, there is a more distributed and decentralized definition of the system configuration, which substantially increases the difficulty of managing the cross-cutting concerns of the organization like security, compliance, and reliability. When these self-contained components are inconsistent across time – from development to testing to staging to production – the challenge increases. The resulting complexity has been an underlying cause of unexpected downtime and security breaches. These days, any organization with a SaaS offering that engages customers via the cloud can recall an incident or close call where the security of their software was made vulnerable or the application experienced unexpected downtime. This comes at great cost to any business. A [2020 Divvy Cloud study](https://divvycloud.com/wp-content/uploads/2020/02/Cloud-Misconfiguration-Report-FINAL.pdf) of publicly reported breaches estimated that 21.2 billion records were exposed in 2019 at the cost of $3.18 trillion. As for downtime, we learned last summer that one to five minutes of downtime cost Google upwards of $500,000 (never mind the cost to those who depend on Google), and an hour of downtime cost Amazon nearly $5 million.
69%of enterprises are moving towards hybrid adoption.
84%of enterprises are adopting a multicloud strategy.
75%of network outages and performance issues result from misconfiguration.
### Advances in Cloud Tech – Greater Speed but Added Complexity In short, today’s application developers benefit from an expanding tools ecosystem that enables faster time to market for new features. However, these new conveniences increase the complexity of managing configurations in development, test, staging, and production environments. The impact of this can be seen in three major areas: {% tabs %} {% tab title="INTERCONNECTED CLOUD SYSTEMS" %} #### Operating in a Fog of Accumulating, Interconnected Cloud Systems The cloud world includes micro services, third-party systems, server-less computing, and a service mesh to connect it all together. The surface area is huge, and the amount of configuration and security information required to stitch it all together creates an unsustainable cognitive load for your team. Worse, each of these new wonderful services often comes with it’s own bespoke configuration approach, and it’s own management tooling. Now more than ever a configuration control plan to begin cutting through the fog. \ \ We don’t live exclusively in the “data center model” anymore: where systems admins and in-house devs built everything for their company. In the “old days”, you had to rely on custom built tooling, and your team had to know how everything worked.\ \ Take, for example, Auth0, a SaaS tool that helps companies manage user identity and access controls without needing to build that capability internally. Services like this speed up development time for companies where authenticating users is necessary but not central enough to the business to justify building equivalent functionality in-house. But here’s the catch: services like Auth0 offer a whole host of different configuration settings and customization options in order to address needs across a wide range of different customer applications. To make the most effective use of these tools, those settings need to be managed appropriately. Compared to an in-house solution that is designed and managed for a single specific use case, this adds more complexity.\ \ Unchecked, this can slow you down when you think it will speed you up, and really hurt your repair efforts when something goes wrong.\ \ The average cloud technology stack subscribes to at least six third-party services, such as Auth0. Multiply that times an increasing number of similar tools in the company’s tech stack, and not only does each of those systems require its own configuration, but the configuration of each system impacts the configurations of other systems. This creates a network effect of exponential complexity. The danger? Any “shared team awareness” across these varied and inter-dependent configurations either dissolves as the development team grows and specializes, or worse, disappears entirely with team change and turnover.Security {% endtab %} {% tab title="CLOUD CHALLENGES" %} * Security * Managing cloud spend * Lack of resources/expertise * Governance/control * Compliance * Managing multiple clouds * Performance * Building a private cloud * No configuration control plan {% endtab %} {% tab title="CUSTOMIZATION AND RELIABILITY/SECURITY" %} #### Choosing between Customization and Reliability/Security As cloud systems grow more complex, configuration change management oversight lags, and that impacts the security and reliability of the entire product in unpredictable ways. Because of inter-dependent functionalities, troubleshooting problems to determine the root cause takes longer and often requires the expertise of senior developers. As a result, a small product reliability bug or security flaw can snowball into a larger issue and exact a productivity hit. Having a configuration control management plan is the first step toward better system performance. Even Google engineers have experienced this. During their outage last summer, according to Benjamin Treynor Sloss, Google’s VP of engineering, “Engineering teams detected the issue within seconds, but diagnosis and correction took far longer than our target of a few minutes. Once alerted, engineering teams quickly identified the cause of the network congestion, but the same network congestion which was creating service degradation also slowed the engineering teams’ ability to restore the correct configurations, prolonging the outage.” One fallback is to stick with the default configuration settings for each tool in the stack, but as soon as a project needs to scale, moving beyond default settings is required to improve performance. Skipping the tuning phase will diminish the value of the tool, which may have been the reason for choosing it in the first place. > **Cloud customers must move beyond the defaults, or risk security problems.** > {% endtab %} {% tab title="ADAPTING TO CLOUD EVOLUTION" %} #### Adapting to Cloud Evolution – Organizational and Process Impact One logical reaction of fast-moving organizations is to attempt to define and build their own tool in-house to manage these systems, but this takes time and resources away from critical product development work. Since developing these tools is only tangentially related to the core business, there is rarely an adequate budget for initial development and ongoing improvements. Bespoke DIY tools often become a spare-time activity and maintenance headache over time. In addition, traditional organizational charts simply don’t account for the additional resources necessary to manage these new, complex systems. In the past, companies hired individual personnel to manage specific systems (for example, A DBA for all the databases, a network engineer for VPN, WAN, etc.), and it would be relatively straightforward to determine the necessary skill set for the job. Today, individual systems are no longer isolated, so developers with experience in single systems will struggle to effectively manage the matrix of tools that comprise the modern tech stack. As such, companies are searching for people with experience in managing complex, multi-layered cloud systems. These cloud operations experts are hard to find because the necessary experience is less common and because it can be difficult to develop quantitative hiring practices and clear job descriptions for the right fit. Finally, the interconnectedness of the various tools that support different parts of the organization can make traditional development team structures less effective. If multiple teams work in parallel on separate components of an integrated system, it can be challenging to ensure coordination between them. This can result in duplicated efforts, conflicting efforts, and other personnel issues that interfere with productivity. Many people start with “out of the box” defaults to reduce complexity, but in the long run, that will only work in the most basic of cases and will negate all the increased efficiency and performance improvement made possible by new, integrated tools. What can organizations do to remove the fog, empower customization without increased risk, and support a more productive team environment? {% endtab %} {% endtabs %} ### Steps to Build Team Visibility + Coordination Around a Single Record of Truth Of course, wherever possible, cloud customers should decouple systems that have become unnecessarily entangled over time. If component tools can work in isolation, there is less risk of a domino effect of taking down the entire system when a single piece has an issue. A cost-benefit analysis of integration for improved efficiency versus system isolation for minimized failure impact needs to be conducted holistically across the entire cloud ecosystem. In addition, integrated systems require integrated teams, which is why cloud customers are hiring for diverse skill sets and restructuring teams to encourage cross-functional collaboration and communication. As organizations adapt to new tools and technologies, ensuring that employees at every level and function — from junior developers to middle management to senior leadership — must communicate openly and effectively. But most importantly, a consolidated view of configurations across all cloud systems – a single record of truth – becomes the glue for teams that now work independently but need to benefit from the learnings of other teams. For simple systems, in-house management tools may be sufficient, but for most scaled-up, tech-savvy companies, a third-party configuration management solution is the missing piece to ensuring that critical systems are always updated and configured properly. At CloudTruth, we are focused on delivering this single view of truth across the cloud via a SaaS configuration orchestration platform with a central configuration data hub that combines all the cloud ecosystem configuration settings and files in a way that: * makes configuration settings understandable to all parts of the organization responsible for application security and support * speeds up access control * builds confidence in the correct provisioning of new releases * makes troubleshooting a matter of minutes rather than hours * facilitates audit and compliance Over time, the analytics and machine learning layer on top of the central configuration database will reveal system tuning best practices (not just individual system settings), automate the prevention of configuration errors, and orchestrate global configuration change implementations. ### Consider these three steps to manage these highly customizable cloud ecosystems:
Evaluation and decoupling of unnecessary integrations
Hiring, training and awareness to support cross-team collaboration
Sharing a single consolidated view of configurations across the ecosystem
### Conclusion Today’s development teams should not feel like they must sacrifice innovation and speed for reliability and security. But efficient guardrails are needed to make this happen.\ \ While building visibility and coordination across many cloud tools is a big undertaking, CloudTruth is dedicated to this goal. We allow development teams to choose and customize best-of-breed tools while maintaining coordination, operations, and infrastructure leaders to focus on performance evolution rather than fire drills. We enable security professionals to look ahead to future risk prevention rather than catching existing threats in the making. # Open Source CloudTruth could not exist without the open source community. One of our core commitments is to give back to the community to benefit others. ## CloudTruth Open Source We provide open source projects such as: * [Kubernetes operator](https://github.com/cloudtruth/kubetruth) * [CLI](https://github.com/cloudtruth/cloudtruth-cli) * [GitHub Actions plugin](https://github.com/cloudtruth/configure-action) * [Argo CD plugin](https://github.com/cloudtruth/argocd-cloudtruth-plugin) * [Terraform provider](https://github.com/cloudtruth/terraform-provider-cloudtruth) * [Import Utility](https://github.com/cloudtruth/importer) * [Circle CI integration](https://github.com/cloudtruth/cloudtruth-cli) [Check out all our open repos on GitHub](https://github.com/cloudtruth) ## Atmos enhances Terraform on AWS Our CTO [Matt Conway](https://www.linkedin.com/in/matthewrbconway/) created Atmos and AWS-Bastion to make our life easier and we hope you find them as useful as we do. Breathe easier with Atmos + Terraform. Cloud system architectures made easy. Atmos provides a layer of organization on top of Terraform for creating cloud system architectures with Amazon Web Services. It handles the plumbing so you can focus on your application. The core Atmos runtime is free and open-source, with a business friendly license (Apache). It provides basic recipes to help get you going with a service-oriented architecture implemented with AWS Elastic Container Services. View the [screencast](https://simplygenius.wistia.com/medias/zamoxtlqe0) for a detailed walkthrough (\~1 hour) of the quickstart. Or try the [condensed screencast](https://simplygenius.wistia.com/medias/2syql5mnud) if you just want to take a quick look (\~7m). [View on GitHub](https://github.com/simplygenius/atmos) ## AWS-Bastion A docker container that provides SSH/VPN by using AWS IAM groups to control which IAM users can SSH using the SSH public key stored for those users in IAM (only they have the private key). This lets a user control SSH/VPN access to a VPC without having to deal with credentials – just put users in the right IAM group to enable them to ssh in and remove them from the group to disable them. Users have full control over the ssh keypair for authentication. [View on GitHub](https://github.com/cloudtruth/aws-bastion)
# FAQs Common questions and answers about the configuration command center ConfigOps platform.
What is CloudTruth? CloudTruth is a [dynamic secrets and config engine](https://www.cloudtruth.com/product?hsLang=en) that helps teams generate accurate, repeatable config and secrets for every deployment. Centralizes access to all secrets, parameters, and ENV variables related to infrastructure provisioning, application configuration, and secrets management. [Input and output integrations](https://www.cloudtruth.com/integrations?hsLang=en) connect with your tools: Kubernetes, Terraform, Cloudformation, Vault, AWS Secret Manager, AWS Parameter Store, Azure Key Vault, GitHub, Ansible, Puppet, and others. With CloudTruth, you gain a single record of truth across all configuration settings, automatic change tracking, improving security, reliability, and team velocity. Configuration is becoming distributed and decentralized, leading to an exponential increase in the settings required by each deployment across multiple environments. This is a hard problem to solve at scale. [PRODUCT](/product)
Why do I need CloudTruth? We interviewed thousands of technology professionals across roles, ranging from CIO, CTO, and CISO to DevOps, SecOps, and QA leaders. We learned that there needs to be a better way to track & orchestrate configuration changes. Nearly everyone uses one tool for infrastructure as code (IaC) techniques to provision infrastructure, another tool to configure applications & services, and a separate third tool to store secrets. With the advent of IaC, Kubernetes, containers, and serverless come new challenges because multiple tools are spread across multiple teams, using hundreds of Git repositories to store configuration settings. ​CloudTruth aggregates all configuration settings into one consolidated view and lets you use the data between tools. Usage examples: * Automatically configure applications from IaC tooling. * Dynamically build and update Kubernetes ConfigMaps and secrets with centralized control. * Track consistency between dev/test, staging, and production environments. * Support multiple environments with inheritances and overrides. * Use dynamic templating to streamline application configuration. * SRE teams need to know what changed, by whom, and when right before an outage or security incident. * Share configuration file changes with team members who don’t have access to original sources (such as compliance, QA, audit & GRC teams.) * QA groups manage multiple environments and need to know if a setting that causes drift from standard configuration settings is changed. * A data science team will want to know when database configurations change before production. * Compliance now has an easier way to track changes system-wide.
What does CloudTruth do? ​CloudTruth is a [ConfigOps platform](https://cloudtruth.com/product) that provides a unified parameter store that can source configuration settings from other locations. Also included is built-in support for multiple environments and static and dynamic templating. CloudTruth can also securely store secrets alongside other configuration data. CloudTruth connects to your existing configuration tools, such as Terraform, Ansible, and Cloudformation, and parameter stores, such as AWS SSM, Vault, and Git repo. This provides a single API, CLI, and GUI to interact with all your configuration data from one place.
Why is CloudTruth different? * **Tool-agnostic**: CloudTruth lives alongside your existing configuration tools and works across multiple environments and IaC solutions. * **Cloud-agnostic**: CloudTruth is focused on the configuration data layer and works with multiple cloud providers. Starting with AWS support now and future support for Azure, GCP, IBM, DO, and other infrastructure providers. * **Focused on change**: Our initial offering is a centralized parameter store that can source settings from other locations such as Terraform, AWS Parameter Store, and JSON/YAML stored in Github. * **Built anticipating the evolution to containers, serverless, and IaC**: Configuration is becoming decentralized and distributed. DevOps, SRE, and core software developers now interact with configuration tools. What’s missing is a single record of truth describing how an organization’s infrastructure and applications are configured.
Where is my data stored? Your configuration data never leaves the source. Parameters and secrets can remain in your existing locations, such as AWS Parameter Store, AWS Secrets Manager, Azure Key Vault, HC Vault, or Git repos. You can also optionally import your config data into CloudTruth. In that case, your data is stored in an AWS RDS database encrypted with an automatically generated KMS key (or you can supply your key.) Additional account and system information are stored in an AWS database service. A self-hosted version is available to keep all your data and processing in your own VPC.
What permissions does CloudTruth need? CloudTruth needs read-only access permissions to in/out integrations such as S3, AWS SSM, and GitHub repositories.
What is the security model? CloudTruth is created by [experienced cloud technologists](https://www.cloudtruth.com/about?hsLang=en) who have previously created massively scalable systems for data backup, archiving, compliance, and governance. We follow the principle of least privilege access policies, with strong boundaries between environments and restricted access to production resources.
# Our Mission ## Meet the Team Hear from CTO Matt Conway, CPO Greg Arnette, and CEO Christian Tate on how we're helping teams tame their secrets and config sprawl to increase release velocity and "deploy more joy." {% embed url="" %} ## Feature Overview A 5-minute screencast on the core features for managing secrets and configurations for all environments, projects, and teams. {% embed url="" %} ## CloudTruth in Action A 5-minute look into using CloudTruth for a popular use case: Managing Kubernetes manifests, ConfigMaps, secrets, and helm charts for multiple dev, staging, and prod without needing overlay values in separate YAML files. {% embed url="" %} # Quick Start Videos CloudTruth setup in less than 5 minutes. ## Our quick start videos make it easy to use CloudTruth. ### The library is on our [YouTube channel](https://www.youtube.com/c/CloudTruthVideos), or choose a video category below. ## [What is CloudTruth?](https://docs.cloudtruth.com/reference/quick-start-videos/what-is-cloudtruth) ## [CloudTruth in Action](https://docs.cloudtruth.com/reference/quick-start-videos/cloudtruth-in-action) ## [Environments and Projects](https://docs.cloudtruth.com/reference/quick-start-videos/cloudtruth-in-action) ## [Secrets, Parameters, ENV variables](https://docs.cloudtruth.com/reference/quick-start-videos/secrets-parameters-env-variables) ## [Audit Logs, RBAC, SSO](https://docs.cloudtruth.com/reference/quick-start-videos/audit-logs-rbac-sso) ## [Containers - Kubernetes, Docker](https://docs.cloudtruth.com/reference/quick-start-videos/containers-kubernetes-docker) ## [Infrastructure as Code (IaC) - Terraform, Cloudformation, CDK, Azure Bicep, Pulumi](https://docs.cloudtruth.com/reference/quick-start-videos/iac-terraform-cloudformation) ## [CICD Pipelines - GitHub Actions, ArgoCD, Jenkins, CircleCI, Harness, GitLab Pipelines](https://docs.cloudtruth.com/reference/quick-start-videos/cicd-argocd-github-actions) ## [AWS Videos - Secret Manager, Parameter Store, S3, IAM](https://docs.cloudtruth.com/reference/quick-start-videos/aws-videos) ## [Azure Videos - Azure DevOps, Azure Bicep, PowerShell](https://docs.cloudtruth.com/reference/quick-start-videos/azure-videos) # What is CloudTruth? ### Learn how the CloudTruth ConfigOps Platform makes complex config easy to use. {% embed url="" %} Meet your new configuration command center {% endembed %} ### Take a deeper dive into CloudTruth features specifically for DevOps and platform engineers. {% embed url="" %} ### This video shows how an application developer can create new config settings and hand them off to DevOps for a production deployment. {% embed url="" %} ### # CloudTruth in Action ### Take a deep dive into the CloudTruth Dynamic Secrets and Config Engine. In this video, you'll learn how CloudTruth makes it easy to manage dynamic environment config with your IaC tool. {% embed url="" %} ### This screencast describes how CloudTruth helps DevOps and Platform teams manage complicated config scenarios. {% embed url="" %} # Environments and Projects ### Managing secrets at scale for multiple environments and projects is easy with the CloudTruth ConfigOps platform. {% embed url="" %} ### Compare multiple environments side-by-side {% embed url="" %} ### Get started with projects {% embed url="" %} # Secrets, Parameters, ENV variables ### Sharing and syncing secrets, parameters, and ENV variables at scale is one way to get your team on the same page and accelerate deployment velocity. Learn how CloudTruth is the easy way to achieve more perfect deploys. {% embed url="" %} ### Manage rules and types. {% embed url="" %} # Audit Logs, RBAC, SSO ### Audit logs, single sign-on, and strong role-based access control ensure your config data is always protected, and you can meet compliance requirements. {% embed url="" %} # Containers - Kubernetes, Docker ### There's a better way to manage ConfigMaps and Secrets for multiple environments with CloudTruth. {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} # Infrastructure as Code (IaC) - Terraform, Cloudformation, CDK, Azure Bicep, Pulumi ### Terraform, CloudFormation, and other IaC tools need good input data to manage infrastructure provisioning. Learn how CloudTruth makes it easy for multiple environments and projects. {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} # CICD Pipelines - GitHub Actions, ArgoCD, Jenkins, CircleCI, Harness, GitLab Pipelines {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} # AWS Videos - Secret Manager, Parameter Store, S3, IAM {% embed url="" %} {% embed url="" %} # Azure Videos - Azure DevOps, Azure Bicep, PowerShell {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} # Knowledge Base ## Welcome to our KB site You can browse the articles by title, but the preferred method is to use the search bar in the top right. If you don't find what you need, let us know via the chat icon on the bottom right. Our Success Team can work with you on a solution and document it so that it is shared with the community. # Best Practices # Versioned Releases A common pattern for managing configuration is to send changes through an approval process. CloudTruth will introduce an approval workflow feature in the future. In the interim, one can accomplish the same goals by using tags against our versioned configuration store. This can be tied into your release cycle or used explicitly to update configuration between releases. It enables you to have a stable set of configurations to make several incremental changes before batching them into a single push to your production systems. One can approximate an approval process with the manual step of only allowing authorized users to update tags to current. ## Creating Tags Tags are intrinsically tied to environments. To create one, go to the Environments page, select the desired environment and click the Create Tag button. Give the tag a name, and optionally select a point in time that the tag represents (defaults to now).
Select the Immutable option to prevent the tag from being updated to reflect recent changes. You can also create tags using the CLI: ``` cloudtruth environments tag set production stable --current ``` ## Referencing Tags Once you have tags set up for your critical environments, you can use them when referencing your configuration at any of our integration points (push actions, Kubernetes operator, CLI, API, etc) #### CLI examples ``` cloudtruth --project backend --env production parameters list --as-of stable --format json cloudtruth --project backend --env production template get dotenv --as-of stable ``` #### Kubernetes Operator Example Use the tag specifier on any project mappings that you desire to use a tag on. You can also specify it globally for all project mappings by use of a helm property override at install time: ``` helm install \ --set appSettings.apiKey= \ --set projectMappings.root.environment=production \ --set projectMappings.root.tag=stable \ kubetruth cloudtruth/kubetruth ``` #### Push Action Example Tags are required for Push Action, as can be seen in the create/edit dialog for a push action:
## Updating Tags To edit a tag, go to the Environment page, select the environment containing the tag, then click the triple-dot menu for the tag and select Edit Tag.
Show the date picker and click in the timestamp field to have the option of selecting a specific timestamp or selecting Now to update the tag to right now, thereby promoting it to contain all current values.
Once updated, any subsequent operations that reference this tag at one of our integration points will now get any updated values. You can also update tags using the CLI, e.g. for use within a CI/CD pipeline: ``` cloudtruth environments tag set production stable --current ``` ## Comparing Changes To approximate an approval process, use the History page to check any Current changes against a tag (works for Parameters and Templates):
# CLI # History comparison of deleted parameters with null values ### Overview Deleted parameters that contained `null` values are not displayed in historical comparisons. Additionally, they do not display `Created At` or `Modified At` Times. A parameter named `empty.empty` contained a `null` value that was deleted . Since the parameter contained a null value `empty.empty` is not displayed in a projects historical differences table. ``` cloudtruth --project Demo parameters differences --as-of 2021-08-26 +-------------------+---------+----------------------+ | Parameter | Current | 2021-08-26T00:00:00Z | +-------------------+---------+----------------------+ | empty | - | | | empty.empty_empty | - | | | lower | - | case | | nil | - | | | pill | red | - | +-------------------+---------+----------------------+ ``` The parameter `empty.empty` displays empty times when searching a project on a previous date. ``` cloudtruth --project Demo parameters ls -v --as-of 2021-08-26 --show-times +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+-----------------------------+-----------------------------+ | Name | Value | Source | Type | Secret | Description | Created At | Modified At | +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+-----------------------------+-----------------------------+ | CHARACTER | NEO | default | internal | false | | 2021-08-25T14:18:59.117018Z | 2021-08-25T14:18:59.117023Z | | TF_VAR_resource_tags | {"Name":"Cloudtruth-Instance","project":"CloudTruth Run Terraform","environment":"default"} | default | internal | false | | 2021-08-25T14:18:59.129339Z | 2021-08-25T14:18:59.129344Z | | empty | | default | internal | false | | 2021-08-25T14:18:59.119914Z | 2021-08-25T14:18:59.119919Z | | empty.empty | - | | internal | false | | | | | empty.empty_empty | | default | internal | false | | 2021-08-25T14:18:59.120008Z | 2021-08-25T14:18:59.120013Z | | lower | case | default | internal | false | | 2021-08-25T14:18:59.122449Z | 2021-08-25T14:18:59.122454Z | | nil | | default | internal | false | | 2021-08-25T14:18:59.122730Z | 2021-08-25T14:18:59.122735Z | | node.name | "${NODE_NAME}" | default | internal | false | | 2021-08-25T14:18:59.122762Z | 2021-08-25T14:18:59.122766Z | | secret | ***** | default | internal | true | | 2021-08-25T14:18:59.123741Z | 2021-08-25T14:18:59.123746Z | | service.app.cpu | 4 | default | internal | false | | 2021-08-25T14:18:59.126921Z | 2021-08-25T14:18:59.126925Z | | service.app.memory | 8 | default | internal | false | | 2021-08-25T14:18:59.126952Z | 2021-08-25T14:18:59.126957Z | | service.demo.timeout | 200 | default | internal | false | | 2021-08-25T14:18:59.127014Z | 2021-08-25T14:18:59.127019Z | +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+-----------------------------+-----------------------------+ ``` ### Resolution You can view a list of values a project contained by directly passing a date to a project and viewing the values and comparing the parameters to a current listing. **Parameters listed as of 2021-08-26** ``` cloudtruth --project Demo parameters ls -v --as-of 2021-08-26 +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+ | Name | Value | Source | Type | Secret | Description | +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+ | CHARACTER | NEO | default | internal | false | | | TF_VAR_resource_tags | {"Name":"Cloudtruth-Instance","project":"CloudTruth Run Terraform","environment":"default"} | default | internal | false | | | empty | | default | internal | false | | | empty.empty | - | | internal | false | | | empty.empty_empty | | default | internal | false | | | lower | case | default | internal | false | | | nil | | default | internal | false | | | node.name | "${NODE_NAME}" | default | internal | false | | | secret | ***** | default | internal | true | | | service.app.cpu | 4 | default | internal | false | | | service.app.memory | 8 | default | internal | false | | | service.demo.timeout | 200 | default | internal | false | | +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+ ``` **Comparing the current parameters** we can find the parameter `empty.empty` is a deleted and contained a null value. ``` cloudtruth --project Demo parameters ls -v +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+ | Name | Value | Source | Type | Secret | Description | +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+ | CHARACTER | NEO | default | internal | false | | | TF_VAR_resource_tags | {"Name":"Cloudtruth-Instance","project":"CloudTruth Run Terraform","environment":"default"} | default | internal | false | | | node.name | "${NODE_NAME}" | default | internal | false | | | pill | red | default | internal | false | | | secret | ***** | default | internal | true | | | service.app.cpu | 4 | default | internal | false | | | service.app.memory | 8 | default | internal | false | | | service.demo.timeout | 200 | default | internal | false | | +----------------------+---------------------------------------------------------------------------------------------+---------+----------+--------+-------------+ ``` # Integrations # Advanced AWS IAM policy permissions ## Creating restrictive IAM integration policies ### Overview Your organizations security policies may require you to restrict CloudTruth integration access to specific [resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html) in your AWS account. CloudTruth verifies integration permissions by querying a key `_cloudtruth_test_`. You will need to provide access to `_cloudtruth_test_*` in the AWS Secret Manager and SSM inline policies in order for the integration status to show connected. Without `_cloudtruth_test_*` allowed the integration status will show the following errors. {% hint style="danger" %} **Secrets Manager Details:** Unable to complete a Secrets Manager operation. Please check your IAM policy for the 'secretsmanager:DescribeSecret' permission. {% endhint %} {% hint style="danger" %} **SSM Details:** Unable to complete an SSM operation. Please check your IAM policy for the 'ssm:GetParameter' permission. {% endhint %} ### **Resolution** Below are examples that add the `_cloudtruth_test_*` resource to your specific inline policy along with a sample included resource. **AWS Secret Manager** This example inline policy allows access to all secrets that start with the prefix `sample` and allows the integration health check `_cloudtruth_test_`. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ListSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "SecretAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": [ "arn:aws:secretsmanager:*:*:secret:sample*", "arn:aws:secretsmanager:*:*:secret:_cloudtruth_test_*" ] } ] } ``` **SSM Parameter store** This example policy allows access to all parameters that start with the prefix `sample` and allows the integration health check `_cloudtruth_test_`. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ParameterList", "Effect": "Allow", "Action": "ssm:DescribeParameters", "Resource": "*" }, { "Sid": "ParameterAccess", "Effect": "Allow", "Action": [ "ssm:GetParametersByPath", "ssm:GetParameters", "ssm:GetParameter" ], "Resource": [ "arn:aws:ssm:*:*:parameter/sample*", "arn:aws:ssm:*:*:parameter/_cloudtruth_test_*" ] } ] } ``` **S3** S3 does not explicitly need a permission to allow `_cloudtruth_test_`. The following is an example on how you can limit the S3 integration to only get data from a specific bucket `YOUR_BUCKET_NAME`. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "BucketSelection", "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" }, { "Sid": "BucketAccess", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::YOUR-BUCKET-NAME/*", "arn:aws:s3:::YOUR-BUCKET-NAME" ] } ] } ``` # K8s pull image from private Docker registry ### Overview This article will show you how various methods utilizing CloudTruth and [KubeTruth ](/configuration-management/integrations/kubernetes#kubetruth)to create a Kubernetes Secret [`type: kubernetes.io/dockerconfigjson`](https://kubernetes.io/docs/concepts/configuration/secret/#secret-types) that allows you to create pods that use this Secret to [pull an image from a private docker registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials) or repository. ### Resolution * Method 1: [kubectl apply from a CloudTruth template.](#method-1-kubectl-apply-from-a-cloudtruth-template) * Method 2: [KubeTruth project mapping override with a base64 encoded Docker configfile.](#method-2-kubetruth-project-mapping-override-with-a-base64-encoded-docker-configfile) * Method 3: [KubeTruth project mapping override with Docker login.](#method-3-kubetruth-project-mapping-override-with-docker-login) #### Method 1: kubectl apply from a CloudTruth template 1. run `docker login` 2. base64 encode your [existing dockerfile](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials) 1. `base64 /home/$USER/.docker/config.json` 3. Add the config.json base64 encoded string as a CloudTruth parameter `type:secret` named `configjson` in a CloudTruth project called K8s. 4. Create a CloudTruth template `regcred` and if required [customize ](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials)the yaml to your namespace. 1. ``` apiVersion: v1 kind: Secret metadata: name: myregistrykey data: .dockerconfigjson: {{configjson}} type: kubernetes.io/dockerconfigjson ``` 5. Run `kubectl apply -f <(cloudtruth --project K8s template get regcred)` 6. You can now [inspect the secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#inspecting-the-secret-regcred) and [use the created secret in pods](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret). `kubectl get secret myregistrykey --output=yaml` #### Method 2: [KubeTruth](/configuration-management/integrations/kubernetes#kubetruth) project mapping override with a base64 encoded Docker configfile 1. run `docker login` 2. base64 encode your [existing dockerfile](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials) 1. `base64 /home/$USER/.docker/config.json` 3. Add the config.json base64 encoded string as a CloudTruth parameter `type:secret` named `configjson` in a CloudTruth project called `K8s`. 4. Create a KubeTruth override in the namespace where KubeTruth is operating that will automatically create the K8s `kubernetes.io/dockerconfigjson` Secret. 1. ``` kubectl apply -n demokubetruth -f - <