Introduction
APIs (Application Programming Interfaces) are the backbone of modern software development, enabling the seamless exchange of data between different applications. Managing APIs effectively is crucial for any organization, and Google Cloud’s Apigee is a leading platform for API management. If you’re using Apigee Hybrid, you can supercharge your deployment and management with the Apigee Hybrid Accelerator Ansible playbook. In this blog post, we’ll explore how to use this playbook to streamline your Apigee Hybrid setup and management.
What is Ansible Apigee Hybrid Accelerator?
The Ansible Apigee Hybrid Accelerator is an open-source solution which contains a set of ansible roles and playbooks to simplify and automate the installation and configuration of Apigee Hybrid clusters. Apigee Hybrid combines the benefits of Apigee’s cloud-native API management with an on-premises runtime environment, offering flexibility, security, and control over your APIs.
Using the Accelerator, you can quickly set up your Apigee Hybrid instance, saving time and reducing the risk of manual configuration errors. Whether you’re new to Apigee or a seasoned user, this playbook can help you get your API management system up and running efficiently.
Why use Ansible for Apigee Hybrid?
Ansible is a powerful automation tool that streamlines complex tasks by defining them as code. This allows for consistent, repeatable, and scalable deployments. When it comes to managing an Apigee Hybrid installation, Ansible simplifies the process by automating tasks like:
- Installing Apigee components
- Configuring Apigee runtime environment settings
- Managing Apigee Northbound TLS certificates
- Performing routine maintenance tasks on Apigee Components
Getting Started with the Ansible Apigee Hybrid Accelerator Playbook
To use the Apigee Hybrid Accelerator Ansible playbook, follow these steps:
Prerequisites
Before you begin, make sure you have the following prerequisites in place:
- Apigee Control plane is set up like Apigee Org , environment , virtualhosts.
- A machine with below tools installed
- Ansible
- Helm
- gcloud CLI
- kubectl- gcloud cli must be authenticated by a user/service account having roles/apigee.admin permission.
- helm cli needs to authenticated if using private registry
- Access to the kube-config file for one of the supported Kubernetes platforms.
- The Apigee Hybrid Accelerator playbook, which you can find on the GitHub repository
Expected Setup
Based on the prerequisites specified above , you will have a set up similar to this.
Setting up the Apigee Hybrid Control Plane
You can use the Apigee terraform module to setup the Apigee Hybrid control plane
Sample usage of the terraform module
module "apigee" {
source = "github.com/terraform-google-modules/cloud-foundation-fabric//modules/apigee"
project_id = "my-project"
organization = {
display_name = "My Organization"
description = "My Organization"
runtime_type = "HYBRID"
analytics_region = "europe-west1"
}
envgroups = {
test = ["test.example.com"]
prod = ["prod.example.com"]
}
environments = {
apis-test = {
display_name = "APIs test"
description = "APIs Test"
envgroups = ["test"]
}
apis-prod = {
display_name = "APIs prod"
description = "APIs prod"
envgroups = ["prod"]
iam = {
"roles/viewer" = ["group:devops@myorg.com"]
}
}
}
}
Clone the Repository
Clone the Ansible Apigee Hybrid Accelerator repository to your Ansible control machine. You can do this using the following command:
git clone https://github.com/apigee/ansible-apigee-hybrid-accelerator
cd ansible-apigee-hybrid-accelerator
Configure the Playbook Variables
Edit the vars.yaml file to include your Apigee Hybrid environment details, such as organization name, environment name and apigee hybrid component configuration credentials.
Cert manager
Set cert manager version in vars.yaml using cert_manager_version
refer: https://cloud.google.com/apigee/docs/hybrid/v1.10/install-cert-manager for more details
cert_manager_version: v1.7.2
Certificates
To configure certificates for Apigee Hybrid use below params in vars.yaml
- generate_certificates : Set to true to generate self signed certifcates
- cert_cn: Set to CN for certificates , used only when generate_certificates: true
generate_certificates: false
cert_cn: apigee.com
Bring your Own Certificates
To configure your own certificates to Apigee Hybrid follow the steps mentioned in link to create secrets and reference them in the overrides.virtualhosts section of vars.yaml
Service Accounts
To configure service accounts for Apigee Hybrid use below params in vars.yaml
- deployment_environment: Set to prod or non-prod to generate service accounts as per doc.
- create_service_account : Set to true to generate service account key JSON and create corrspongin K8s Secret
- synchronizer_prod_svc_account: If create_service_account=false , provide a service account name to be configured for the synchronizer component.
create_service_account: false
deployment_environment: prod
synchronizer_prod_svc_account: apigee-hybrid-user
Bring your Service Account
To configure your own GCP service accounts to Apigee Hybrid , download the service account key JSON and create a generic secret using the below command .
kubectl create secret generic SECRET_NAME \
--from-file="client_secret.json=CLOUD_IAM_FILE_NAME.json" \
-n apigee
Once the secret is created, reference them in the overrides section of vars.yaml for relevant components.
Helm Details
To configure Helm chart details for Apigee Hybrid use below params in vars.yaml
- helm_chart_repo: Helm Repo containing the Apigee Hybrid Helm charts.
- helm_chart_version : Version of helm charts to be pulled
- helm_charts: Array of helm charts to be pulled for Apigee Deployment.
helm_chart_repo: oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
helm_chart_version: 1.10.3
helm_charts:
- apigee-operator
- apigee-datastore
- apigee-env
- apigee-ingress-manager
- apigee-org
- apigee-redis
- apigee-telemetry
- apigee-virtualhost
You can use your own private helm_chart_repo and reference in the vars.yaml , but this requires you to authenticate the helm cli prior to running the playbook.
Kube Configs
To configure Kubernetes kube-config for Apigee Hybrid use below params in vars.yaml
- primary: Path to primary kube-config to deploy Apigee Hybrid.
- secondary: Path to second kube-config to deploy Apigee Hybrid in multi DC mode.This is OPTIONAL , if you only need single region setup you can avoid this.
kubeconfigs:
primary: <path to primary kubeconfig>
secondary: <path to secondary kubeconfig>
Validations
To configure details for post setup API validation use below params in vars.yaml
- internet_access: Set this to true to enable public mock API validations.
- validate_api_redeploy: Set this to true to redeploy mock apis
internet_access: true
validate_api_redeploy: false
Overrides/Helm Values
To fill the overrides section refer the Configuration property reference | Apigee | Google Cloud
Refer the example in vars.yaml
Ansible Tags
The playbook exposes tags to selectively run tasks depending on the need.
Below are the tags that are exposed in the playbook
Ansible Tag |
Functionality |
|---|---|
dc1 |
Deploy Apigee Hybrid on Primary kube-config |
dc2 |
Deploy Apigee Hybrid on Secondary kube-config |
ao |
Deploy apigee-operator Helm Chart |
apigee-virtualhost |
Deploy apigee-virtualhost Helm Chart |
apigeeds |
Deploy apigee-datastore Helm Chart |
apigeeenv |
Deploy apigee-env Helm Chart |
apigeeingress |
Deploy apigee-ingress-manager Helm Chart |
apigeeorg |
Deploy apigee-org Helm Chart |
apigeeorgs |
Deploy apigee-org Helm Chart |
apigeeredis |
Deploy apigee-redis Helm Chart |
apigeetelem |
Deploy apigee-telemetry Helm Chart |
at |
Deploy apigee-telemetry Helm Chart |
bootstrap-apigee-crds |
Deploy Apigee CRDS |
cert-manager |
Deploy Cert Manager |
certs |
Create Certificates for VirtualHost |
ds |
Deploy apigee-datastore Helm Chart |
enable-synchronizer |
Enable Apigee synchronizer |
generate-overrides |
Generate Apigee Overrides |
prepare-helm |
Download Apigee Hybrid Helm charts |
prepare-service-accounts |
Create Service Keys & K8s Secrets |
validate-input |
Validates the inputs given to the playbook |
validate |
Validate Apigee Hybrid By deploying & invoking mock API |
wait_ao |
Wait for apigee-operator to be up |
wait_apigeeenv |
Wait for apigee enviornment custom resource to be running |
wait_apigeeingress |
Wait for apigee ingress to be up |
wait_apigeeorg |
Wait for apigee-org custom resource to be running |
wait_apigeeredis |
Wait for apigee-redis to be up |
wait_at |
Wait for apigee-telemetry to be up |
wait_ds |
Wait for apigee-datastore (cassadra) to be up |
wait_virtualhost |
Wait for apigee-route-config custom resource to be running |
Running the Playbook
To run the playbook use the ansible-playbook command and specify the playbook.The playbook will execute the necessary tasks to set up and configure your Apigee Hybrid environment based on the parameters you’ve provided.
Below are some of the usage patterns.
Primary DC Installation Only
To deploy Apigee Hybrid in 1 Region only run the ansible playbook as shown below
ansible-playbook playbook.yaml -e @vars/vars.yaml --tags "dc1"
Primary & Secondary DC Installation Only
To deploy Apigee Hybrid in 2 Regions run the ansible playbook as shown below
ansible-playbook playbook.yaml -e @vars/vars.yaml
Decommission Primary DC Only
To decommission Apigee Hybrid in the first region run the ansible playbook as shown below
ansible-playbook decommission.yaml -e @vars/vars.yaml --tags dc1
Decommission Primary & Secondary DC
To decommission Apigee Hybrid from both Regions run the ansible playbook as shown below
ansible-playbook decommission.yaml -e @vars/vars.yaml
Apigee Hybrid Component management
To manage components via playbook you need to run playbook while passing the selective ansible tag.Some scenarios are listed below
Validate the provided inputs
To validate the inputs given to ansible
ansible-playbook playbook.yaml -e @vars/vars.yaml --tags "validate-input"
Validate the current setup
To validate a running setup by executing mock APIs.
ansible-playbook playbook.yaml -e @vars/vars.yaml --tags "validate"
To Update Apigee VirtualHost
To update the Apigee Virtual Hosts.
ansible-playbook playbook.yaml -e @vars/vars.yaml --tags "validate-input,generte-overrides,apigee-virtualhost,wait_virtualhost,validate"
Tips for Success
Here are some tips to make your experience with the Apigee Hybrid Accelerator Ansible playbook more successful:
- Ensure your ansible control machine has proper access to your Apigee Hybrid environment and the necessary permissions to perform configuration tasks.
- Regularly update the playbook from the GitHub repository to take advantage of bug fixes and new features.
- Review the playbook’s documentation and customize it to fit your specific requirements. The playbook is highly configurable, allowing you to tailor it to your environment.
- Backup your existing configurations and data before running the playbook to avoid any data loss or unexpected behavior.
Conclusion
The Apigee Hybrid Accelerator Ansible playbook is a valuable tool for organizations looking to streamline the setup and management of their Apigee Hybrid API management platform. By automating many of the complex and error-prone tasks, this playbook can help you save time and ensure your API management system is configured correctly and securely.
If you’re using Apigee Hybrid, consider giving the Apigee Hybrid Accelerator Ansible playbook a try. It’s a step towards achieving a more efficient, consistent, and scalable API management environment.
For more details and updates, visit the GitHub repository and explore the documentation. Happy API management!
In this blog post, we discussed the usage of the Apigee Hybrid Accelerator Ansible playbook to simplify and automate the deployment and management of Apigee Hybrid. Ansible, coupled with the helm, offers a powerful solution for organizations looking to optimize their API management setup.