Changelogs
Overview
The APIM API ingredient allows for easy registration & modification of APIs within an Azure APIM resource.
Ingredient Name
@azbake/ingredient-apim-api
How to include in a recipe
name: My package
shortName: mypkg
version: 0.0.1
ingredients:
- "@azbake/ingredient-apim-api@~0" #include the latest version of the ingredient at build time
parallelRegions: false #typically we only want to deploy to the primary region, so can turn off parallel deploy
resourceGroup: false #If the recipe only contains an apim api deployment, you don't need to create resource groups
How to use as an ingredient instance
recipe:
apim-api-deploy:
properties:
type: "@azbake/ingredient-apim-api" #ingredient type
source: "<azure_resource_group_name>/<azure_apim_resource_name>" #identity the azure apim resource to register an API against
condition: "[coreutils.primary_region()]" #make sure we only execute this against the primary region for multi-region configs
parameters:
... #see documentation below on parameter documentation for how to use.
Parameters
Here is the documentation for all the supported paremeters for this ingredient.
options
options:
apiWaitSeconds: <number> # Supply a number of seconds to wait for any xml-link/swagger-link urls to become availabile
# before creating the APIM api/policy/etc.
# You might be deploying a new API in this recipe, which could take 30-120s to become online.
# This setting lets us wait for new APIs to be online
forceWait: <boolean> # forces bake to wait the `apiWaitSeconds` value even if the API exists. Useful for allowing a
# k8s service deployment to update when using the same version.
apiRetries: <number> # number of times the ingredient will retry to add the API
apiRetryWaitTime: <number> # seconds between retries
apis
apis: #follows this azure spec for *ApiVersionSetContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3215
- name: <api-version-name> #unique id for the API (version set) - required
versions:
- versionSchema #See next section for version schema
api[n].versions
versions: #follows this azure spec for *ApiCreateOrUpdateParameter* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L180
- name: <api-name> #typically you want set the id to <api-version-id>-<version> to keep the id consistant for the version set it belongs to - required
version: <string> #version string that will be used as part of the above ApiVersionSetContract.versioningSchema
products: #optional list of product names to assign API to
policies: #see next section for policy schema
diagnostics: #see next section for diagnostic schema
Note: ApiCreateOrUpdateParameter.serviceUrl and ApiCreateOrUpdateParameter.value support being defined as BakeVariables. This allows you to set these two values as an expression to resolve endpoint/data dynamically during deployment
api.versions[n].policies
policies: #scheme follows this azure spec for *PolicyContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3097
- operation: <string> #optional, and if not set this will be the default policy set for the entire api. Otherwise, name of an operation within this api to apply the policy to.
api.versions[n].diagnostics
diagnostics: #follows this azure spec for *DiagnosticSettingsResource* : https://github.com/Azure/azure-sdk-for-js/blob/20fe312b1122b21811f9364e3d95fe77202e6466/sdk/monitor/arm-monitor/src/models/index.ts#L991
- name: <diagnostics name> #required name of diagnostics settings
Utility Functions
Utility classes can be used inside of the bake.yaml file for parameter and source values.
apimapi class
| Function | Returns | Description |
|---|---|---|
get_api(resourceGroup: string, apimName: string, apiId: string) | Promise<ApiGetResponse> | Returns the API for a given set of parameters. |
get_backend(resourceGroup: string, apimName: string, backendId: string) | Promise<BackendGetResponse> | Returns the back end for a given set of parameters. |
get_hostheader(namespace: string, k8sHostname: string, serviceName: string) | string | Returns host header for API |
get_swaggerUrl(namespace: string, k8sHostname: string, version: string, serviceName: string, protocol: string) | string | Returns swagger url page for the API |
Utility function examples
variables:
api: "[await apimapi.get_api(<apim resource group>, <apim name>, <api id>)]"
backend: "[await apimapi.get_backend(<apim resource group>, <apim name>, <backend id>)]"
hostHeader: "[await apimapi.get_hostheader(<api namespace>, <k8sHostName>)]"
swaggerUrl: "[await apimapi.get_swaggerUrl(<api namespace>, <k8sHostName>), <api version>]"
Sample
name: my-api
shortName: myApi
owner: owner
version: 1.0.0
ingredients:
- "@azbake/ingredient-apim-api@~0"
- "@azbake/ingredient-app-insights@~0"
resourceGroup: false #no need to create a resource group, just assigning to existing APIM instance
parallelRegions: false
variables:
url: http://petstore.swagger.io/v2/swagger.json
aiName: "[appinsights.get_resource_name('apim-api')]"
apimName: "[apim.get_resource_name('api')]"
apimResourceGroup: "[apim.get_resource_group()]"
# build the source from helper functions
apimSource: "[apim.get_resource_group() + '/' + apim.get_resource_name('api')]"
recipe:
my-api-deploy:
properties:
type: "@azbake/ingredient-apim-api"
source: "[coreutils.variable('apimSource')]" #point to existing APIM resource to add API
condition: "[coreutils.primary_region()]"
parameters:
options:
apiWaitTime: 60 # override to waiting up to 60s for the API to be ready
forceWait: true # force wait 60s before updating the API in APIM
apiRetries: 2 # retry adding the API this number of times
apiRetryWaitTime: 5 # number of seconds between retries
apis:
- name: petstore #unique API version identifier across APIM
displayName: Pet Store API
description: Pet Store API description
versioningScheme: Segment
versions:
- name: petstore-v1 # unique API identifer across APIM
version: v1
apiType: http
path: pets #base apim url for this api
protocols: #array of http and/or https
- https
format: swagger-link-json #using a swagger link the value needs to be a http based json document to download
value: "[coreutils.variable('url')]" #value supports bake variables.
products:
- petstore-product #product should already be created. if needed you can import APIM ingredient and deploy in the same recipe
- starter
policies:
- format: xml #we use a non-link format here to embed the policy, but this could have been xml-link and a http address
value: <policies>
<inbound />
<backend>
<forward-request />
</backend>
<outbound>
<set-header name="X-Powered-By" exists-action="delete" />
<set-header name="X-AspNet-Version" exists-action="delete" />
<set-header name="CustomHeader" exists-action="override">
<value>{{expressionApiDisplay}}</value>
</set-header>
</outbound>
</policies>
- operation: addPet #override the addPet operation policy
format: xml
value: "<policies> <inbound /> <backend> </backend> <outbound /></policies>"
diagnostics:
- name: applicationinsights
loggerId: "[(await apim.get_logger(await coreutils.variable('apimResourceGroup'), await coreutils.variable('apimName'), 'aiapim-api')).id]"
sampling:
samplingType: fixed
percentage: 50
- name: petstore-v2 # unique API identifer across APIM
version: v2
apiType: http #unless you're using soap
path: pets #base apim url for this api
protocols: #array of http and/or https
- https
format: swagger-link-json #using a swagger link the value needs to be a http based json document to download
value: "[coreutils.variable('url')]" #value supports bake variables.
products:
- petstore-product
policies:
- format: xml #we use a non-link format here to embed the policy, but this could have been xml-link and a http address
value: <policies>
<inbound />
<backend>
<forward-request />
</backend>
<outbound>
<set-header name="X-Powered-By" exists-action="delete" />
<set-header name="X-AspNet-Version" exists-action="delete" />
</outbound>
</policies>
- operation: addPet #override the addPet operation policy
format: xml
value: "<policies> <inbound /> <backend> </backend> <outbound /></policies>"