Before you start working on this project, you'll need to install several tools to ensure your development environment is properly set up.
You will need an Integrated Development Environment (IDE) to write and manage your code efficiently. We recommend Visual Studio Code (VSCode) because of its flexibility and a wide range of available extensions for Terraform and Git integration.
- Terraform: Provides syntax highlighting, linting, and IntelliSense for Terraform files.
- YAML: Useful for working with GitHub Actions workflows.
- GitLens: Enhances Git capabilities within VSCode, showing Git blame information, commit history, and more.
- Prettier - Code Formatter: Ensures consistent formatting of your code.
Git is essential for version control and managing your project’s source code. Install it from the official website based on your operating system:
Once Git is installed, you can verify the installation by running the following command in your terminal or command prompt:
git --version
After installing Git, you need to configure your user information. This information is used to track who made the changes in the Git commit history.
Run the following commands to set your Git username and email globally (this can be specific to your GitHub account or organization).
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
To verify that the configuration was successful, run:
git config --global --list
Terraform is required to manage the infrastructure resources in this project. You can download it from the official Terraform website:
After installing Terraform, verify the installation by running the following command:
terraform --version
- Create a New Repository: Start by forking or cloning this repository into your GitHub account.
- Clone and Push to Your New Repository: If cloning then take a local copy of this repo and then push it to your newly created repository:
git clone https://github.com/deploymenttheory/terraform-demo-jamfpro.git
cd terraform-demo-jamfpro
git remote set-url origin https://github.com/your-username/your-new-repo.git
git push -u origin main
Replace your-username and your-new-repo with your GitHub username and the name of your new repository.
- Configure Terraform Cloud Workspaces:
To manage your Jamf Pro infrastructure across different environments, you'll need to set up workspaces in Terraform Cloud. Follow these steps:
-
Create Project: Create a new project in Terraform Cloud for your Jamf Pro infrastructure.
-
Create Workspaces:
Assigned to your project Create three workspaces in Terraform Cloud:
terraform-jamfpro-sandbox
terraform-jamfpro-staging
terraform-jamfpro-production
Use
API-driven workflow
for each workspace. -
Tag Workspaces: Tag each of these workspaces with the "jamfpro" tag. This allows you to easily identify and group these workspaces.
-
Set Up Variable Set for Common Variables: Create a variable set for variables that are common across all environments, set the following variables as
Terraform variable
:a. In Terraform Cloud, go to your organization settings. b. Click on "Variable sets" and then "Create variable set". c. Name it something like "Jamf Pro Common Variables". d. Add the following variables:
enable_client_sdk_logs
: Set to "false"client_sdk_log_export_path
: Set to "" - emptyjamfpro_jamf_load_balancer_lock
: Set to "true"jamfpro_token_refresh_buffer_period_seconds
: Set to "100"jamfpro_mandatory_request_delay_milliseconds
: Set to "300"
f. Apply this variable set to all three Jamf Pro workspaces.
-
Configure Workspace-Specific Variables: For each workspace, set the following variables as
Terraform variable
:a. Go to the workspace settings in Terraform Cloud. b. Navigate to the "Variables" section. c. Add the following variables:
jamfpro_instance_fqdn
: The FQDN of your Jamf Pro instance for this environment.jamfpro_client_id
: Your Jamf Pro client ID (for OAuth2)jamfpro_client_secret
: Your Jamf Pro client secret (for OAuth2)jamfpro_basic_auth_username
: Your Jamf Pro username (for basic auth)jamfpro_basic_auth_password
: Your Jamf Pro password (for basic auth)
d. Mark sensitive variables (like passwords and secrets) as sensitive.
-
Access Controls: Set up appropriate access controls for each workspace:
a. Go to the "Team Access" section in each workspace's settings. b. Assign the appropriate permissions to team members based on their roles and the environment. c. Consider restricting access to production workspaces to a smaller group of trusted team members.
-
Version Control Settings: Configure version control settings for each workspace:
a. Go to the "Version Control" section in the workspace settings. b. Connect the workspace to your GitHub repository. c. Set the VCS branch to match your environment branches (e.g., "sandbox", "staging", "production").
Remember, keeping your Terraform Cloud configuration secure is crucial. Always use environment variables for sensitive information, and never commit secrets to your version control system.
By following these steps, you'll have a well-organized and secure setup in Terraform Cloud, with proper separation between environments and efficient management of common variables.
- Configure Github Secrets: Set up the following secrets in your GitHub repository settings:
TF_API_TOKEN
: Your Terraform Cloud API token for Terraform Cloud backend. this can be generated from the Terraform Cloud UI under account settings -> Tokens -> create api token.PAT_TOKEN
: Your GitHub Personal Access Token for branch management operations.
To set up the PAT_TOKEN: a. Go to your GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens. b. Click "Generate new token". c. Give your token a descriptive name, e.g., "Terraform Jamf Pro Config Branch Management". d. Set the expiration as per your security policies. e. Under "Repository access", select "Only select repositories" and choose the repository you're setting up. f. Under "Permissions", grant the following permissions:
- Repository permissions:
- Contents: Read and write (This allows branch management)
- Metadata: Read-only (This is required for API operations)
- Organization permissions:
- Members: Read-only (If working within an organization)
g. Click "Generate token" and copy the token immediately. h. In your repository, go to Settings > Secrets and variables > Actions. i. Click "New repository secret", name it PAT_TOKEN, and paste your token as the value.
Optional:
MSTEAMS_WEBHOOK_URL
: Your Microsoft Teams webhook URL for sending notifications.SLACK_WEBHOOK_URL
: Your Slack webhook URL for sending notifications.
To set up the notification webhooks:
a. For Microsoft Teams:
- In your Teams channel, click the '...' next to the channel name and select 'Connectors'.
- Find 'Incoming Webhook' and click 'Configure'.
- Provide a name for your webhook and optionally upload an image.
- Click 'Create' and copy the webhook URL provided.
- In your GitHub repository, go to Settings > Secrets and variables > Actions.
- Click "New repository secret", name it MSTEAMS_WEBHOOK_URL, and paste the webhook URL as the value.
b. For Slack:
- Go to your Slack workspace's App Directory and create a new app (or use an existing one).
- Under 'Features', select 'Incoming Webhooks' and activate them.
- Click 'Add New Webhook to Workspace' and select the channel for notifications.
- Copy the webhook URL provided.
- In your GitHub repository, go to Settings > Secrets and variables > Actions.
- Click "New repository secret", name it SLACK_WEBHOOK_URL, and paste the webhook URL as the value.
These webhook URLs are used in the Send Notification workflow (send-notification.yml) to send deployment status updates to your team. The workflow determines which service to use based on the notification_channel input. Here's a snippet of how it's used:
-
Configure Terraform Cloud Secrets: Set up the following secrets in your Terraform Cloud workspace variable settings for each environment (Sandbox, Staging, Production):
JAMFPRO_INSTANCE_FQDN
: Your Jamf Pro instance URL. For example:https://your-instance.jamfcloud.com
.JAMFPRO_AUTH_METHOD
: Can be eitherbasic
oroauth2
.JAMFPRO_CLIENT_ID
: Your Jamf Pro client id whenJAMFPRO_AUTH_METHOD
is set to 'oauth2'.JAMFPRO_CLIENT_SECRET
: Your Jamf Pro client secret whenJAMFPRO_AUTH_METHOD
is set to 'oauth2'.JAMFPRO_BASIC_AUTH_USERNAME
: Your Jamf Pro username whenJAMFPRO_AUTH_METHOD
is set to 'basic'.JAMFPRO_BASIC_AUTH_PASSWORD
: Your Jamf Pro user password whenJAMFPRO_AUTH_METHOD
is set to 'basic'.
Note: For Terraform Cloud, when setting variables you do not need to prefix your env vars with
TF_VAR_
as Terraform Cloud automatically does this for you. Additionally, ensure to select the variable category asTerraform variable
, with the HCL tickbox unchecked. -
Update Terraform Variables: Modify the
terraform
block in your.tf
files to match your Jamf Pro instance details. For example:provider "jamfpro" { jamfpro_instance_fqdn = var.jamfpro_instance_fqdn jamfpro_load_balancer_lock = var.jamfpro_jamf_load_balancer_lock auth_method = var.jamfpro_auth_method client_id = var.jamfpro_client_id client_secret = var.jamfpro_client_secret log_level = var.jamfpro_log_level log_output_format = var.jamfpro_log_output_format log_console_separator = var.jamfpro_log_console_separator log_export_path = var.jamfpro_log_export_path export_logs = var.jamfpro_export_logs hide_sensitive_data = var.jamfpro_hide_sensitive_data token_refresh_buffer_period_seconds = var.jamfpro_token_refresh_buffer_period_seconds mandatory_request_delay_milliseconds = var.jamfpro_mandatory_request_delay_milliseconds }
It's strongly recommended for beginners to ensure that
jamfpro_load_balancer_lock
is set to true, to avoid any issues with the Jamf Pro load balancer. -
Backend Configuration: For our multi-environment setup, we'll be using Terraform workspaces. This approach allows us to use a single set of configuration files while maintaining separate states for each environment. Here's how to structure it:
In your main Terraform configuration file (e.g.,
main.tf
):terraform { cloud { organization = "deploymenttheory" workspaces { tags = ["Jamf Pro"] } } }
This configuration tells Terraform to use Terraform Cloud with the "deploymenttheory" organization and to work with any workspace tagged with "jamfpro".
-
Terraform Provider Configuration: Specify the provider source and version:
terraform { required_providers { jamfpro = { source = "deploymenttheory/jamfpro" version = "0.1.12" } } }
-
Define Your Resources: Use Terraform resource definitions to manage your Jamf Pro resources.
-
Create a New Branch: When starting work on a new feature, bug fix, or any other change, create a new branch with an appropriate prefix. This naming convention is enforced by our workflows and helps categorize the type of work being done.
Use one of the following prefixes based on the nature of your work:
feat-
: For new featuresfix-
: For bug fixesdocs-
: For documentation changesstyle-
: For formatting, missing semi colons, etc; no code changerefactor-
: For refactoring production codetest-
: For adding missing tests, refactoring tests; no production code changechore-
: For updating grunt tasks etc; no production code changebuild-
: For changes that affect the build system or external dependenciesci-
: For changes to our CI configuration files and scriptsperf-
: For performance improvements
To create a new branch:
-
Ensure you're on the main branch and it's up to date:
git checkout main git pull origin main
-
Create and switch to a new branch with an appropriate prefix:
git checkout -b prefix-branch-name
Replace
prefix-
with one of the prefixes listed above, andbranch-name
with a brief, descriptive name for your change.For example:
git checkout -b feat-add-user-authentication
-
Make your changes on this new branch.
-
Push your branch to the remote repository:
git push -u origin prefix-branch-name
This naming convention helps our automated workflows identify the type of change and process it accordingly. It also makes it easier for team members to understand the purpose of each branch at a glance.
-
Make Changes and Push: Make your changes and push to GitHub.
-
Test in Sandbox: The
01 - terraform testing: sandbox
workflow will automatically run. -
Promote to Sandbox: After testing your changes in your feature branch, you can promote them to the Sandbox environment. This process involves creating a pull request to merge your feature branch into the
sandbox
branch. Here's how to do it:
-
Ensure all your changes are committed and pushed to your feature branch.
-
Go to your repository on GitHub.
-
Click on the "Pull requests" tab.
-
Click the "New pull request" button.
-
Set the base branch to
sandbox
and the compare branch to your feature branch. -
Give your pull request a descriptive title and provide details about the changes in the description.
-
Click "Create pull request".
-
Request a review from your team members if required by your team's process.
-
Once the pull request is approved, merge it into the
sandbox
branch.
Important: The actual application of changes to the Sandbox environment is handled automatically by the "02 - terraform apply to: sandbox" workflow. This workflow is triggered when a pull request is merged into the sandbox
branch.
After merging:
- The workflow will automatically start.
- It will apply the Terraform changes to the Sandbox environment.
- You can monitor the progress of this workflow in the "Actions" tab of your GitHub repository.
Remember: Always verify that the workflow completes successfully. If there are any issues, they will be reported in the workflow run logs.
By following this process, you ensure that your changes are properly promoted to the Sandbox environment and applied in a controlled, automated manner.
-
Promote to Staging: Now manually trigger the
02-release-and-plan-staging.yml
workflow and approve the pull request to merge the release branch into thestaging
branch after change review. -
Apply to Staging:
This project uses an automated process for creating versions and preparing releases when promoting changes from the Sandbox environment to Staging. This process is implemented in the 03 - release and terraform plan to: staging
workflow. Here's an overview of how it works:
The release process is initiated manually. To start this process:
- Go to the "Actions" tab in your GitHub repository.
- Find the "03 - release and terraform plan to: staging" workflow.
- Click "Run workflow".
- Select the
sandbox
branch as the base for the release. - Click "Run workflow" to start the process.
Once triggered, the workflow performs the following steps:
-
Version Creation:
- The workflow automatically determines the next version number based on semantic versioning principles.
- It creates a new tag with this version number.
- A new release is created in GitHub with this tag.
-
Branch Creation:
- A new branch is created with the name pattern
release-v{version}-to-staging
. - This branch contains all the changes that were in the
sandbox
branch.
- A new branch is created with the name pattern
-
Terraform Plan:
- The workflow runs a Terraform plan against the Staging environment.
- This plan shows what changes will be applied to the Staging environment if this release is approved.
-
Pull Request Creation:
- A pull request is automatically created to merge the release branch into the
staging
branch. - The pull request description includes:
- The new version number
- A summary of the Terraform plan (resources to be added, changed, or destroyed)
- A link to the full Terraform plan in Terraform Cloud
- A pull request is automatically created to merge the release branch into the
After the workflow completes:
- Review the pull request and the Terraform plan carefully.
- If everything looks correct, approve and merge the pull request.
- Merging the pull request will trigger the "04 - terraform apply to: staging" workflow, which will apply the changes to the Staging environment.
- Always review the Terraform plan before approving the release to Staging.
- The version number is automatically incremented. You don't need to manually manage version numbers.
- Each release creates a permanent tag in your repository's history, making it easy to track what changes were included in each release.
- If you need to make changes after creating a release but before applying to Staging, you can push additional commits to the release branch before merging the pull request.
This automated process ensures consistent versioning, provides a clear history of releases, and allows for a final review before applying changes to the Staging environment.
-
Promote to Production: Repeat the process for promoting to Production by manually triggering the
04-release-and-plan-production.yml
workflow and approving the pull request to merge the release branch into theproduction
branch after change review. -
Apply to Production: After the pull request is merged, the
05-terraform-apply-production.yml
workflow will automatically run to apply the changes to the Production environment.