ABOMIS Airports Apigee API Proxy CI/CD

Key Features • Methodology • The Why? • Background • Getting Started • Author

Welcome to abomis-airports repository!

Within this repository you will find a reference solution for API proxy CI/CD Azure pipeline for Apigee using Apigee Deploy Maven Plugin & Apigee Config Maven Plugin.

📝 Note: This solution is following apigee/devrel CI/CD guidelines and example.

Key Features

Supports Apigee X / Hybrid.
Follows best practices.
Fully Decoupled CI/CD.
High maintainabilty.
Cost effective as your pipeline will only trigger to changes in source code.
Highly flexible.

Methodology

1. Tools and Dependencies

This solution is using:

Static Apigee proxy code analysis using apigeelint (standalone via node).
Static JS code analysis using eslint (standalone via node).
JS resources unit testing using mocha (standalone via node).
Creation of Apigee configurations using Apigee Config Maven Plugin (in Maven via plugin).
Packaging and deployment of the API proxy bundle using Apigee Deploy Maven Plugin (in Maven via plugin).
Integration testing of the deployed proxy using apickli + CucumberJS (standalone via node).
CI/CD solution using Azure Pipelines.
apigee-core-yaml-pipeline-templates framework.

2. Folder Structure and Naming Conventions

An API developer will have to allocate single repository per API proxy where he can manage the proxy as a code:

The repository name should be: {COMPANY_NAME}-{API_NAME}.
The API proxy name on the organization should be: {COMPANY_NAME}-{API_NAME}-{API_VERSION}.
The API proxy base path should be the same as your API proxy name.
The API proxy base path should be: /{COMPANY_NAME}-{API_NAME}/{API_VERSION}.
Within pom.xml file:
```
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <groupId>{GROUP_ID}</groupId>
  <artifactId>{PROXY_NAME}</artifactId>
  <version>{API_VERSION}</version>
  <name>{PROXY_NAME}${deployment.suffix}-${project.version}</name>
  ...
  <properties>
      <proxy.filename>{API_PROXY_ROOT_FILE}</proxy.filename>
      ...
  </properties>    
</project>
```
📝 Notes:
- {GROUP_ID}: uniquely identifies your project across all projects. A group ID should follow Java's package naming rules. This means it starts with a reversed domain name you control. For example com.abomis.
- {PROXY_NAME} should be your API proxy name without appending the version. For example abomis-airports.
- {VERSION} should be your API version. For example v1.
- ${deployment.suffix} is a property that defaults to an empty string and you can customize it.
- {API_PROXY_ROOT_FILE} should be equal to the name of the .xml file found at apiproxy/ dir. For example abomis-airports-v1.xml.
- Make sure that you update the following when you release a new API version:
  1. <version></version> within pom.xml.
  2. <proxy.filename></proxy.filename> with the new API proxy root file within the pom.xml
  3. Base path within your proxy source code with the new version.

Folder structure:

.
├── .eslintrc.json      // used to configure eslint tool
├── .gitignore.json
├── README.md
├── pom.xml
├── package.json
├── package-lock.json
├── apiproxy/           // your api proxy source code
│   ├── {PROXY_NAME}-{VERSION}.xml
│   ├── policies/
│   ├── proxies/
│   └── resources/
├── cicd/
│   ├── build.yaml
│   └── release.yaml
├── docs/
│   └── assets/
├── resources
│   └── edge/            // your api proxy config files
└── test/
    ├── integration/     // your functional test scripts
    └── unit/            // your unit test scripts

💡 Tip: see resources/edge multi-file config structure docs.

The Why?

Enterprises and teams should use source code control and CI/CD for proxy development and deployment (configuration management).
Too easy to lose or overwrite revisions of your API when using the UI.

Background

Apigee is a platform for developing and managing APIs. By fronting services with a proxy layer, Apigee provides an abstraction or facade for your backend service APIs and provides security, rate limiting, quotas, analytics, and more.

Apigee enables you to provide secure access to your services with a well-defined API that is consistent across all of your services, regardless of service implementation. A consistent API:

Makes it easy for app developers to consume your services.
Enables you to change the backend service implementation without affecting the public API.
Enables you to take advantage of the analytics, developer portal, and other features built into Apigee.

Rather than having app developers consume your services directly, they access an API proxy created on Apigee.

💡 Learn More: Understanding APIs and API proxies.

An API proxy is a thin application program interface that exposes a stable interface for an existing service or services.

API proxies allow developers to define an API without having to change underlying services in the back end. This works by decoupling the front-end API from the back-end services, which is what shields the app from code changes on the back end. The benefit to an API proxy is that it is essentially a simple and lightweight API gateway.

An API proxy consists of a bundle of XML configuration files and code (such as JavaScript and Java).

Getting Started

1. Prerequisites

Existing Apigee X / Hybrid organization.
Existing Apigee environment(s) & environment group(s).
Existing two Azure DevOps pipelines with proper service connections:
1. One for the build, suggested naming convention: <REPO_NAME>-ci.
2. One for the release, suggesting naming convention: <REPO_NAME>-cd.
Existing Azure DevOps environment(s).
Technical knowledge of API proxy as code management and configuration (proxies, targets, policies, kvms,...etc).
Technical knowledge of Azure DevOps pipelines to operate and customize the stages if needed.
Preferred but not required to have technical knowledge of Maven's pom.xml file to customize your deployment if needed.
Preferred but not required to have technical knowledge of Npm's package.json file to customize if needed.
GCP service account with the following roles (or a custom role with all required permissions):
- apigee.environmentAdmin
- apigee.apiAdmin
- apigee.admin (Required only for org-level config)

💡 Tip: see Apigee roles.

Create service account key and download it's key:

gcloud iam service-accounts keys create "${SA_NAME}"-key.json --iam-account="${SA_EMAIL}" --key-file-type=json

💡 Tip: SA_EMAIL = {SA_NAME}@{PROJECT_ID}.iam.gserviceaccount.com

2. Initialize a GitHub Repository

Create a GitHub repository

GIT_URL='https://github.com/ORG/REPO.git'

git clone https://github.com/ShehabEl-DeenAlalkamy/abomis-airports.git
cd abomis-airports
git init
git remote add origin2 "${GIT_URL}"
git checkout -b feature/cicd-pipeline
git add .
git commit -m "initial commit"
git push -u origin2 feature/cicd-pipeline

3. Run the Pipeline

Create Variable Groups for your pipeline following these naming conventions:
- <REPO_NAME>-common:
  - For common variables that are the same on all environments.
  - Should contain:
    - org: Apigee's organization.
    - proxyDesc: Contains your API proxy description.
    - gcpServiceAccount: paste the content of your your GCP service account key file as a WHOLE.
    ⚠️ Warning: Make sure to check "Keep this value secret".
- <REPO_NAME>-{ENVIRONMENT}-env:
  - For variables that are environment dependent.
  - Should contain:
    - env: Apigee environment to deploy your API proxy to.
    - hostname: Your specified hostname within your environment group.
    ⚠️ Warning: Make sure to properly configure your DNS to route your hostname to your Apigee organization.

Update:

build pipeline:

The following are the supported params:

parameters:
  buildProfile: # how to build your API proxy, each buildProfile has a type, a name and a version
    type: {{ build_profile_type }} # 'api-proxies' value is the only supported value
    name: {{ build_profile_name }} # add 'mvn-plugins'. 'oas2apigee' & 'mvn-plugins' are supported
    version: {{ build_profile_version }} # add '1'. '1' is the only supported value
  variableGroups:
    - {{ <REPO_NAME>-common }} # your common variables, for example 'abomis-airports-common'

release pipeline:

The following are the supported params:

parameters:
  releaseProfile: {{ release_profile }} # which Azure DevOps environments to deploy to, currently 'custom-release' is the only supported value
  deploymentProfile: # how to deploy your API proxy, each deploymentProfile has a type, a name and a version
      type: {{ deployment_profile_type }} # 'api-proxies' value is the only supported value
      name: {{ deployment_profile_name }} # add 'mvn-plugins'. 'oas2apigee' & 'mvn-plugins' are supported
      version: {{ deployment_profile_version }} # add '1'. '1' is the only supported value      
  artifactAlias: {{ build_pipeline_resource_identifier }} # can be specified in resources.pipelines[0].pipeline
  artifactName: {{ proxy_bundle_artifact_name }} # by default it is named 'proxy-bundle-artifacts' in your build pipeline
  commonVariableGroups:
    - {{ <REPO_NAME>-common }} # your common variables, for example 'abomis-airports-common'
  releaseList: # required for 'custom-release' release profile, specify list of your deployment environments
    - stageName: {{ stage_name }} # identifier for you stage, for example 'Dev'
      displayName: {{ display_name }} # display name shown in your release pipeline run, for example 'Dev'
      variableGroups: # your environment specific variables, for example 'abomis-airports-dev-env'
        - {{ <REPO_NAME>-<ENVIRONMENT>-env }}
      environment: {{ azure_devops_environment }} # your deployment environment, for example 'abomis-dev'
    ...
  apigeeConfigList: # required if deploymentConfig.customApigeeConfig is true, contains all the list of configurations you wish to create only regardless of source code
    - {{ apigee_config_item }} # supported values are [references, keystores, aliases, targetservers, keyvaluemaps, resourcefiles, apiproducts, developers, reports, flowhooks]
    ...
  deploymentConfig: # (optional) alters the deployment templates framework behavior
    customApigeeConfig: {{ true || false }} # enable/disable custom apigee configuration creation, default is false and will attempt to create all the supported configs

💡 Tip: see apigee-core-yaml-pipeline-templates framework.

Configure:
- Build pipeline YAML source to be at: cicd/build.yaml.
- Release pipeline YAML source to be at: cicd/release.yaml.
Run your build pipeline by clicking on "Run Pipeline" button.
Check your build pipeline:

By default, your build pipeline was built to follow best practices by consuming all of the tests results to have a unified UI to see the tests results. It was also built to generate a coverage report to help you determine the proportion of your project's code that is actually being tested by your unit tests. click on the "Tests" tab:

Tests Results (Static Code Analysis + Unit Tests)

Code Coverage Report

Your build pipeline produces two artifacts by default:
- proxy-bundle-artifacts - Contains all of the artifacts needed by your release pipeline to deploy.
- Code Coverage Report_<id> - Autogenerated by the build pipeline for your coverage report.

Pipeline Artifacts

On your main/master, your release pipeline will be auto triggered and start releasing your API proxy to your specified releaseList environments.
Check your release pipeline:

Production environment has been configured to require manual approval

You can check your functional testing results in the 'Tests' tab:

Tests Results (Functional Testing for 3 environments)

Check your Apigee organization's API proxies:

Check your Apigee organization's developers:

📝 Note: Within the solution I added me as a developer inside Apigee organization.

Test your API proxy on all of your environments:

Congratulations! you have deployed your first API proxy successfully : )

⚔️ Developed By

Shehab El-Deen Alalkamy

📖 Author

Shehab El-Deen Alalkamy

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ABOMIS Airports Apigee API Proxy CI/CD

Key Features

Methodology

1. Tools and Dependencies

2. Folder Structure and Naming Conventions

The Why?

Background

Getting Started

1. Prerequisites

2. Initialize a GitHub Repository

3. Run the Pipeline

⚔️ Developed By

📖 Author

About

Releases 3

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 125 Commits
apiproxy		apiproxy
cicd		cicd
docs/assets/imgs		docs/assets/imgs
resources/edge		resources/edge
test		test
.eslintrc.yml		.eslintrc.yml
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pom.xml		pom.xml

alalkamys/abomis-airports

Folders and files

Latest commit

History

Repository files navigation

ABOMIS Airports Apigee API Proxy CI/CD

Key Features

Methodology

1. Tools and Dependencies

2. Folder Structure and Naming Conventions

The Why?

Background

Getting Started

1. Prerequisites

2. Initialize a GitHub Repository

3. Run the Pipeline

⚔️ Developed By

📖 Author

About

Resources

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages