Introduction

ashwinknaik · ‎10-13-2023

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

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.

grsiepka · ‎10-30-2023

Wow this is great. Was planning on writing my own ansible playbook for this but will be checking this out. Haven't dug into this yet but could this be used to upgrade from a 1.9.x installation of Hybrid?

ashwinknaik · ‎10-30-2023

@grsiepka : You should be able to do a blue green upgrade from 1.9.x to 1.10.3+
For this you should be have the kubeconfigs variable with below config

kubeconfigs:
  primary: /app/old_dc1.config  # Set this to kubeconfig of old 1.9 cluster
  secondary: /app/new_dc2.config # Set this to kubeconfig of new K8s cluster to deploy 1.10

Ensure the you send the right DC value for cassandra_dc , Below is an example of doing the upgrade.

ansible-playbook playbook.yaml -e @vars/vars.yaml -e "apigee_source_dc=<old_dc_value>" -e "cassandra_dc=<new_dc_value>" --tags "dc2" 

Example:

ansible-playbook playbook.yaml -e @vars/vars.yaml -e "apigee_source_dc=dc-1" -e "cassandra_dc=dc-2" --tags "dc2"

NOTE: This has not been tested , please try in your lower environment first.

DineshMannam · ‎11-29-2023

Awesome, Thank you Ashwin for putting this together, will be trying this out soon

Accelerate your Apigee Hybrid management with Ansible & Helm

Introduction

What is Ansible Apigee Hybrid Accelerator?

Why use Ansible for Apigee Hybrid?

Getting Started with the Ansible Apigee Hybrid Accelerator Playbook

Prerequisites

Expected Setup

Setting up the Apigee Hybrid Control Plane

Clone the Repository

Configure the Playbook Variables

Cert manager

Certificates

Bring your Own Certificates

Service Accounts

Bring your Service Account

Helm Details

Kube Configs

Validations

Overrides/Helm Values

Ansible Tags

Running the Playbook

Tips for Success

Conclusion