Skip to content

Latest commit

 

History

History
484 lines (394 loc) · 19.5 KB

azurerm-apim.md

File metadata and controls

484 lines (394 loc) · 19.5 KB

Contoso API Management Module

Table of Contents

  1. Overview
  2. Version History
  3. Deployed Resources
  4. Pre-requisites
  5. Contoso Naming Convention
  6. Examples
  7. Input arguments and outputs

Overview

Azure API Management (APIm) is a fully managed service that enables organisations to create, publish, secure, monitor, and analyse APIs in a scalable and reliable environment. It acts as a gateway for backend services, allowing developers to expose their APIs to external and internal consumers while applying policies for security, throttling, caching, and transformation, thus ensuring consistent and controlled API access. You can configure the named values as you want.

Learn more about API Management at Microsoft Learn

Version History

Version Date Description
v1.3.1 17/09/2024 Added support for custom hostnames and improved logging.
v1.3.0 01/08/2024 Enhanced security policies and fixed minor bugs.
v1.2.5 15/06/2024 Introduced caching policies and optimised performance.
v1.2.0 10/05/2024 Added monitoring and analytics features.
v1.1.0 20/03/2024 Initial release with basic API management functionalities.

Deployed Resources

The following resources will be deployed when using Contoso's APIM module:

  • azurerm_api_management
  • azurerm_network_security_rule
  • azurerm_api_management_logger
  • azurerm_api_management_backend
  • azurerm_api_management_named_value
  • azurerm_role_assignment
  • azurerm_key_vault_access_policy (optional - Used for certificates on custom hostnames)
  • azurerm_api_management_custom_domain (optional - Used for custom hostnames)

Pre-requisites

Make sure to update the Terraform versions and providers according to your specific needs.

  • Minimum Terraform version: >= 1.8.0
  • AzureRM provider version: ~> 4.2.0

Before deploying Contoso's APIM module, ensure the following Azure resources are in place:

  • Resource Group (required): Essential for organising and managing related Azure resources.
  • Virtual Network (required): Provides network isolation and security for the APIM instance.
  • Delegated Subnet (required): A subnet with an address space of /28 or larger within the virtual network to host the APIM instance.
  • NSG (required): Network Security Groups associated with the subnet to control inbound and outbound traffic, enhancing security.
  • KeyVault (required): Securely stores and manages sensitive information such as API keys, secrets, and certificates.
  • Log Analytics Workspace (optional): Used for monitoring and analysing logs generated by the APIM instance. Beneficial but not mandatory.
  • App Insights (optional): Provides performance monitoring and diagnostics for the APIM instance. Useful for insights but not essential.
  • Certificate Stored in KeyVault (optional): Required if custom domain names or SSL certificates are needed. Store these in KeyVault based on deployment requirements.

Contoso Naming convention

Contoso's naming convention for the APIM module follows a structured format to ensure consistency and clarity across resources. The naming convention is derived from the following variables environment and project:

Construct: "conto-${var.environment}-${var.project}-apim"
Example Naming: conto-dev-prj-apim

Examples

module.tf

Module usage example:

module "apim" {
  source                                             = "git::ssh://git@ssh.dev.azure.com/v3/Contoso/Contoso-Modules/azurerm_api_management?ref=v1.3.1"

  // Required inputs:
  resource_group_name                                = var.resource_group_name
  subnet_names                                       = var.subnet_names
  virtual_network_resource_group_name                = var.virtual_network_resource_group_name
  nsg_name                                           = var.nsg_name
  publisher_name                                     = var.publisher_name
  backend_services                                   = var.backend_services

  // Optional inputs:
  project                                            = var.project
  environment                                        = var.environment
   
  //See the "## Input arguments and outputs" section for all available options or "variables.tf"
  // If not specified, the default values on "variables.tf" will be applied
}

module.tf.tfvars

Example input values for the APIM module variables:

// Required inputs:
resource_group_name                 = "conto-dev-pclip-rg"
subnet_names                        = ["apim"]
virtual_network_resource_group_name = "conto-dev-pclip-network-rg"
nsg_name                            = "conto-dev-pclip-apim-nsg"
publisher_name                      = "Contoso ApiManager"
backend_services                    = ["admin-services-api", "user-services-api"]

// Optional inputs:
project                             = "pclip
environment                         = "uat"

// See the "## Input arguments and outputs" section for all available options or "variables.tf"
// If not specified, the default values on "variables.tf" will be applied

variables.tf

Example variable definitions for the APIM module:

// Required Inputs

variable "resource_group_name" {
  description = "Resource group name"
  type        = string
}

variable "subnet_names" {
  description = "The name of the subnet for the Azure resources."
  type        = list(string)
}

variable "virtual_network_name" {
  description = "The name of the virtual network for the Azure resources."
  type        = string
}

variable "virtual_network_resource_group_name" {
  description = "The name of the resource group that contains the virtual network."
  type        = string
}

variable "nsg_name" {
  description = "NSG name of the subnet hosting the APIM to add the rule to allow management if the APIM is private"
  type        = string
}

variable "publisher_name" {
  description = "The name of publisher/company."
  type        = string
}

variable "backend_services" {
  description = "Include backend setting in case are needed"
  type        = list(string)
}

// Optional Inputs

variable "additional_location" {
  description = "List of the name of the Azure Region in which the API Management Service should be expanded to."
  type        = list(map(string))
  default     = []
}

variable "app_insights_name" {
  description = "In case you want to integrate APIM with application insights please specify name"
  type        = string
  default     = null
}

variable "backend_protocol" {
  description = "Protocol for the backend http or soap"
  type        = string
  default     = "http"
}

variable "certificate_configuration" {
  description = "List of certificate configurations"
  type        = list(map(string))
  default     = []
}

variable "client_certificate_enabled" {
  description = "Enforce a client certificate to be presented on each request to the gateway? This is only supported when SKU type is `Consumption`."
  type        = bool
  default     = false
}

variable "create_management_rule" {
  description = "Whether to create the NSG rule for the management port of the APIM. If true, nsg_name variable must be set"
  type        = bool
  default     = true
}

variable "custom_management_rule_name" {
  description = "Custom NSG rule name for APIM Management."
  type        = string
  default     = "default-management-apim-rule"
}

variable "developer_portal_host_name" {
  description = "Name for the developers portal URL"
  type        = string
  default     = null
}

variable "developer_portal_hostname_configuration" {
  description = "Developer portal hostname configurations"
  type        = list(map(string))
  default     = []
}

variable "enable_http2" {
  description = "Should HTTP/2 be supported by the API Management Service?"
  type        = bool
  default     = false
}

variable "enable_sign_in" {
  description = "Should anonymous users be redirected to the sign in page?"
  type        = bool
  default     = false
}

variable "enable_sign_up" {
  description = "Can users sign up on the development portal?"
  type        = bool
  default     = false
}

variable "environment" {
  description = "The environment. e.g. dev, qa, uat, prod"
  type        = string
  default     = "dev"
}

variable "gateway_disabled" {
  description = "Disable the gateway in main region? This is only supported when `additional_location` is set."
  type        = bool
  default     = false
}

variable "gateway_host_name" {
  description = "Name for the gateway URL"
  type        = string
  default     = null
}

variable "identity_ids" {
  description = "A list of IDs for User Assigned Managed Identity resources to be assigned. This is required when type is set to UserAssigned or SystemAssigned, UserAssigned."
  type        = list(string)
  default     = []
}

variable "identity_type" {
  description = "Type of Managed Service Identity that should be configured on this API Management Service"
  type        = string
  default     = "SystemAssigned"
}

variable "key_vault_name" {
  description = "Name of the Key Vault where the secrets are read"
  type        = string
  default     = null
}

variable "keyvault_named_values" {
  description = "Map containing the name of the named values as key and value as values. The secret is stored in keyvault"
  type        = list(map(string))
  default     = []
}

variable "location" {
  description = "The default location where the resource will be created"
  type        = string
  default     = "uksouth"
}

variable "management_host_name" {
  description = "Name for the management portal URL"
  type        = string
  default     = null
}

variable "management_hostname_configuration" {
  description = "List of management hostname configurations"
  type        = list(map(string))
  default     = []
}

variable "management_nsg_rule_priority" {
  description = "Priority of the NSG rule created for the management port of the APIM"
  type        = number
  default     = 101
}

variable "min_api_version" {
  description = "The version which the control plane API calls to API Management service are limited with version equal to or newer than."
  type        = string
  default     = null
}

variable "named_values" {
  description = "Map containing the name of the named values as key and value as values"
  type        = list(map(string))
  default     = []
}

variable "notification_sender_email" {
  description = "Email address from which the notification will be sent"
  type        = string
  default     = null
}

variable "policy_configuration" {
  description = "Map of policy configuration"
  type        = map(string)
  default     = {}
}

variable "portal_hostname_configuration" {
  description = "Legacy portal hostname configurations"
  type        = list(map(string))
  default     = []
}

variable "project" {
  description = "The name of the project. e.g. PRJ"
  type        = string
  default     = "prj"
}

variable "proxy_hostname_configuration" {
  description = "List of proxy hostname configurations"
  type        = list(map(string))
  default     = []
}

variable "publisher_email" {
  description = "The email of publisher/company."
  type        = string
  default     = "test.user@contoso.com"
}

variable "requires_custom_host_name_configuration" {
  description = "If APIM requires custom hostname configuration"
  type        = bool
  default     = false
}

variable "scm_hostname_configuration" {
  description = "List of scm hostname configurations"
  type        = list(map(string))
  default     = []
}

variable "security_configuration" {
  description = "Map of security configuration"
  type        = map(string)
  default     = {}
}

variable "sku_name" {
  description = "String consisting of two parts separated by an underscore. The first part is the name, valid values include: Developer, Basic, Standard and Premium. The second part is the capacity"
  type        = string
  default     = "Basic_1"
}

variable "terms_of_service_configuration" {
  description = "Map of terms of service configuration"
  type        = list(map(string))
  default     = [
    {
      consent_required = false
      enabled          = false
      text             = ""
    }
  ]
}

variable "virtual_network_type" {
  description = "The type of virtual network you want to use, valid values include: None, External, Internal."
  type        = string
  default     = "Internal"
}

variable "wildcard_certificate_key_vault_name" {
  description = "Name of the keyvault containing the certificate"
  type        = string
  default     = null
}

variable "wildcard_certificate_key_vault_resource_group_name" {
  description = "Resource group containing certificate keyvault"
  type        = string
  default     = null
}

variable "wildcard_certificate_name" {
  description = "Name of the certificate"
  type        = string
  default     = null
}

variable "zones" {
  description = "Specifies a list of Availability Zones in which this API Management service should be located. Changing this forces a new API Management service to be created. Supported in Premium Tier."
  type        = list(number)
  default     = [1, 2, 3]
}

main.tf

terraform {
  backend "azurerm" {}
}

provider "azurerm" {
  features {}
  resource_provider_registrations = "none"
}

Input arguments and outputs

Inputs

Name Description Type Default Required
additional_location List of the name of the Azure Region in which the API Management Service should be expanded to. list(map(string)) [] no
app_insights_name In case you want to integrate APIM with application insights please specify name string null no
backend_protocol Protocol for the backend http or soap string "http" no
backend_services Include backend setting in case are needed list(string) n/a yes
certificate_configuration List of certificate configurations list(map(string)) [] no
client_certificate_enabled Enforce a client certificate to be presented on each request to the gateway? This is only supported when SKU type is Consumption. bool false no
create_management_rule Whether to create the NSG rule for the management port of the APIM. If true, nsg_name variable must be set bool true no
custom_management_rule_name Custom NSG rule name for APIM Management. string "default-management-apim-rule" no
developer_portal_host_name Name for the developers portal URL string null no
developer_portal_hostname_configuration Developer portal hostname configurations list(map(string)) [] no
enable_http2 Should HTTP/2 be supported by the API Management Service? bool false no
enable_sign_in Should anonymous users be redirected to the sign in page? bool false no
enable_sign_up Can users sign up on the development portal? bool false no
environment The environment. e.g. dev, qa, uat, prod string "dev" no
gateway_disabled Disable the gateway in main region? This is only supported when additional_location is set. bool false no
gateway_host_name Name for the gateway URL string null no
identity_ids A list of IDs for User Assigned Managed Identity resources to be assigned. This is required when type is set to UserAssigned or SystemAssigned, UserAssigned. list(string) [] no
identity_type Type of Managed Service Identity that should be configured on this API Management Service string "SystemAssigned" no
key_vault_name Name of the Key Vault where the secrets are read string null no
keyvault_named_values Map containing the name of the named values as key and value as values. The secret is stored in keyvault list(map(string)) [] no
location The default location where the resource will be created string "uksouth" no
management_host_name Name for the management portal URL string null no
management_hostname_configuration List of management hostname configurations list(map(string)) [] no
management_nsg_rule_priority Priority of the NSG rule created for the management port of the APIM number 101 no
min_api_version The version which the control plane API calls to API Management service are limited with version equal to or newer than. string null no
named_values Map containing the name of the named values as key and value as values list(map(string)) [] no
notification_sender_email Email address from which the notification will be sent string null no
nsg_name NSG name of the subnet hosting the APIM to add the rule to allow management if the APIM is private string null no
nsg_rg_name Name of the RG hosting the NSG if it's different from the one hosting the APIM string null no
policy_configuration Map of policy configuration map(string) {} no
portal_hostname_configuration Legacy portal hostname configurations list(map(string)) [] no
project The name of the project. e.g. PRJ string "prj" no
proxy_hostname_configuration List of proxy hostname configurations list(map(string)) [] no
publisher_email The email of publisher/company. string "test.user@contoso.com" no
publisher_name The name of publisher/company. string null no
requires_custom_host_name_configuration If APIM requires custom hostname configuration bool false no
resource_group_name Resource group name string n/a yes
scm_hostname_configuration List of scm hostname configurations list(map(string)) [] no
security_configuration Map of security configuration map(string) {} no
sku_name String consisting of two parts separated by an underscore. The first part is the name, valid values include: Developer, Basic, Standard and Premium. The second part is the capacity string "Basic_1" no
subnet_names The name of the subnet for the Azure resources. list(string) n/a yes
terms_of_service_configuration Map of terms of service configuration list(map(string)) 
[
  {
    "consent_required": false,
    "enabled": false,
    "text": ""
  }
]
 no
virtual_network_name The name of the virtual network for the Azure resources. string n/a yes
virtual_network_resource_group_name The name of the resource group that contains the virtual network. string n/a yes
virtual_network_type The type of virtual network you want to use, valid values include: None, External, Internal. string "Internal" no
wildcard_certificate_key_vault_name Name of the keyvault containing the certificate string null no
wildcard_certificate_key_vault_resource_group_name Resource group containing certificate keyvault string null no
wildcard_certificate_name Name of the certificate string null no
zones Specifies a list of Availability Zones in which this API Management service should be located. Changing this forces a new API Management service to be created. Supported in Premium Tier. list(number) 
[
  1,
  2,
  3
]
 no

Outputs

No outputs.