AWS CDK è uno dei migliori strumenti per la creazione di infrastrutture su AWS, tramite linguaggi di programmazione come Python o Javascript. Molto velocemente sta diventando sempre più stabile e completo, tuttavia presenta ancora una piccola mancanza nella creazione di API tramite lo standard OpenApi.
Distribuire una API tramite una specifica OpenApi è sicuramente la via migliore considerando tutto l’ecosistema che si è creato interno a questo standard. Purtroppo il suo utilizzo in AWS CDK rimane ancora acerbo. Infatti se distribuire, tramite costrutti CDK, una API tramite il servizio AWS API Gateway è di base relativamente semplice ma prolisso, può diventare intricato utilizzando un file OpenApi.
In questo articolo vedremo come poter risolvere l’integrazione con una Lambda function creata tramite CDK e daremo una possibile soluzione per l’integrazione di un Authorizer tramite Cognito UserPool.
Problema
CDK supporta perfettamente la creazione di una API, tramite il servizio AWS API Gateway, utilizzando lo standard OpenApi e le varie estensioni messe a disposizione. Tuttavia sorgono numerosi problemi nel momento in cui si vanno ad effettuare delle integrazioni dinamiche con servizi come, ad esempio, Lambda o Cognito. Infatti nella specifica del nostro file OpenApi si richiede l’ARN della funzione Lambda o l’ID della User Pool di Cognito, ma questi dati non sono disponibili immediatamente (al primo deploy) in CDK.
Nello specifico vedremmo come l’ARN o l’ID non sarebbero disponibili per popolare il nostro yaml o json, della specifica OpenAPI, il quale viene convertito come asset durante la procedura di Synth della CDK cli, prima che venga fatto il deploy dei servizi. Essendo, quindi, questi dati disponibili solo dopo la creazione dei servizi non possiamo effettuare il rilascio di tutti i servizi, almeno non in contemporanea.
Esempio di integrazione AWS API Gateway + Lambda, tramite OpenAPI:
|
1 2 3 4 5 6 7 8 9 10 11 |
paths: /users: get: summary: List of users responses: 200: # ... x-amazon-apigateway-integration: # API Gateway extension uri: !Sub "arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${your-lambda-arn}/invocations" httpMethod: "POST" type: "aws_proxy" |
Tramite questo spezzone di definizione si va ad indicare ad API Gateway di collegare l’endpoint /users alla funzione Lambda con l’ARN definito nel campo uri ( ${your-lambda-arn} ) ed usando un tipo di integrazione aws_proxy (specifiche dell’estenzione AWS).
Tramite questo esempio ci è forse subito chiaro il problema: dobbiamo conoscere l’ARN della nostra funzione Lambda affinché funzioni l’integrazione, cosa che non sappiamo poiché verrà creata dinamicamente da CDK.
Il team di AWS CDK è a conoscenza di questo problema (vedi la pull-request Github #1461), tuttavia questa issue è aperta da quasi tre anni, quindi nel frattempo abbiamo dovuto trovare una buona soluzione alternativa.
Metodi di risoluzione
Sono state pubblicate diverse soluzioni alternative per questo problema:
- Questo post sul blog di Martin Müller in cui sostanzialmente distribuisce l’intero stack due volte: una volta senza le specifiche OpenAPI e una volta con esse. Non è il tipo di approccio che ci piace utilizzare.
- Questa risposta StackOverflow in cui l’autore utilizza la funzione
Fn::Subnel file OpenAPI per sostituire un segnaposto dell’ARN Lambda con l’ARN effettivo. Questo metodo sarebbe stato il migliore, ma sfortunatamente anche dopo numerosi tentativi non siamo riusciti a farlo funzionare. Questa soluzione avrebbe permesso la sostituzione del segnaposto come succede per gli altriAWS::Partion,AWS::Region,AWS::Account, etc che sono integrati in AWS e disponibili al rilascio del servizio Api Gateway.
Avendo scartato queste due soluzioni abbiamo approcciato quella che attualmente va per la maggiore tra gli utenti, ovvero sostituire l’ARN della Funziona Lambda al momento del Synthesize CDK e quindi al momento della creazione dell’asset di definizione OpenApi. L’unico “svantaggio” che comporta questa soluzione è il dover anticipatamente aver definito in maniera statica il nome della Lambda.
Anche se questa è una soluzione subottimale, la riteniamo ad ogni modo migliore delle altre riportate.
Implementazione soluzione
La definizione OpenAPI è stata creata in un modello Jinja2 in modo che i segnaposto, nel nostro caso il nome della Lambda, possa essere sostituito. Oltre alla sostituzione del nome possiamo così applicare costrutti Jinja, come loop o if, per la creazione di definizioni diverse in base all’ambiente di rilascio.
Esempio di integrazione AWS API Gateway + Lambda, tramite OpenAPI e Jinja2:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
paths: /users: get: summary: List of users responses: 200: # ... x-amazon-apigateway-integration: # API Gateway extension type: "aws_proxy" uri: !Sub "arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:{{ lambda_a }}/invocations" httpMethod: "POST" credentials: "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/{{ lambda_exec_role }}" |
Come si può notare nel campo uri abbiamo aggiunto un ARN che verrà per la maggior parte sostituito automaticamente da AWS e, per la restante parte, tramite Jinja nei segnaposto racchiusi nelle doppie parentesi graffe. In questo caso avremo bisogno di una costante con il nome della Lambda e un’altra con il nome della IAM Role da assegnare al metodo Api-Gateway per poterla eseguire.
Vediamo quindi un esempio (più o meno completo) di uno Stack CDK scritto in Python:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
from aws_cdk import ( core as cdk, aws_apigateway as apigw, .... ) from jinja2 import Environment, FileSystemLoader, select_autoescape # Create a Jinja2 env to load OpenApi3 yaml templateLoader = FileSystemLoader(searchpath="./") env = Environment( loader=templateLoader, autoescape=select_autoescape(['yaml']) ) openapi3_template_path = 'open-api-definition/openapi3.yaml' lambda_exec_role = 'UsersCRUDApiRole' lambda_name = 'get_user_list' class ApiGatewayLambdaStack(cdk.Stack): def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None: super().__init__(scope, construct_id, **kwargs) ############### # API GATEWAY # ############### # Create role with Invoke permission aws_api_role = iam.Role( self, 'UsersCRUDApiLambdaInvokeRole', role_name=lambda_exec_role, assumed_by=iam.ServicePrincipal('apigateway.amazonaws.com'), description="Policy to execute the target Lambda") aws_api_role.add_to_policy( iam.PolicyStatement( effect=iam.Effect.ALLOW, resources=[ f"arn:aws:lambda:{self.region}:{self.account}:function:{lambda_name}" ], actions=["lambda:InvokeFunction"] ) ) # Load a specific stage template from file rendered_openapi3_spec = 'open-api-definition/openapi3_rendered.yaml' template = env.get_template(openapi3_template_path) rendered_text = template.render( lambda_exec_role=lambda_exec_role, lambda_a=lambda_name ) # save the rendered results with open(rendered_openapi3_spec, "w") as file: file.write(rendered_text) # Create an API from OpenApi3 specification api_definition = apigw.AssetApiDefinition.from_asset(rendered_openapi3_spec) api = apigw.SpecRestApi( self, 'UsersCRUDApi', api_definition=api_definition, rest_api_name=f'users-crud-api', endpoint_types=[apigw.EndpointType.REGIONAL], retain_deployments=True) ########## # LAMBDA # ########## lambda_a_role = iam.Role( self, "LambdaARole", description="Policy", assumed_by=iam.ServicePrincipal('lambda.amazonaws.com'), managed_policies=[iam.ManagedPolicy.from_aws_managed_policy_name("service-role/AWSLambdaBasicExecutionRole")]) lambda_a_code = lambda_.Code.from_asset(<lambda_assets>) lambda_a = lambda_.Function( self, "LambdaA", function_name=lambda_name, code=lambda_a_code, handler="lambda_a.lambda_handler", runtime=lambda_.Runtime.PYTHON_3_8, role=lambda_a_role) |
Descriviamo le parti principali del codice: la nostra definizione OpenApi (open-api-definition/openapi3.yaml) viene processata tramite Jinja e quindi esportata una copia dove avremo i nostri due campi (lambda_a, lambda_exec_role) sostituiti (open-api-definition/openapi3_rendered.yaml). Il file viene quindi utilizzato per creare la nostra API tramite il costrutto CDK SpecRestApi(). Infine viene definita la funzione Lambda e tramite il metodo add_permission() facciamo in modo che API-Gateway abbia il permesso di invocare la funzione.
Come è facilmente intuibile questa soluzione non è sicuramente molto elegante ed aggiunge la necessità di definire a priori il nome di tutte le Lambda.
In aggiunta è bene notare che in alcuni casi, dove la IAM Role ha dei permessi molto lascivo, è necessario aggiungere esplicitamente il permesso dell’API-Gateway per invocare ogni singola Lambda. Questo porta inesorabilmente ad un codice più prolisso e statico.
|
1 2 3 4 5 6 |
# Add permission to the specified Api-Gateway method to execute this Lambda lambda_a.add_permission( f"LambdaApiPermission", principal=iam.ServicePrincipal('apigateway.amazonaws.com'), action='lambda:InvokeFunction', source_arn=f"arn:aws:execute-api:{api.env.region}:{api.env.account}:{api.rest_api_id}/*/GET/users" ) |
OpenApi Authorizer integrazione Cognito
AWS Cognito è molto utile nel caso si voglia aggiungere un fattore di autenticazione, tramite Token JWT, per le chiamate all’API. I due servizi: Cognito ed API-Gateway, sono perfettamente integrati in AWS e l’integrazione tramite AWS Web-Console risulta relativamente semplice ed immediata.
Tuttavia non possiamo utilizzare lo stesso metodo visto precedentemente per le Lambda per integrare Cognito come Authorizer in API-Gateway. Infatti ci è impossibile conoscere l’ID della UserPool prima che questa venga creata. L’unico modo attualmente possibile è quello di rilanciare successivamente il deploy, questa volta inserendo l’ID della UserPool precedentemente creata e restituitaci negli output di CloudFormation.
Questo un esempio di integrazione AWS API-Gateway + OpenAPI + AWS Cognito:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
securitySchemes: Bearer_Token_Authentication: type: apiKey name: Auth in: header description: Bearer Token Authentication x-amazon-apigateway-authtype: "cognito_user_pools" x-amazon-apigateway-authorizer: providerARNs: - "arn:${AWS::Partition}:cognito-idp:${AWS::Region}:${AWS::AccountId}:userpool/{{ user_pool_id }}" type: "cognito_user_pools" authorizerResultTtlInSeconds: '10' |
La variabile user_pool_id dovrà essere al primo rilascio casuale e successivamente quella corretta. Al secondo deploy potremmo passare la variabile tramite context di CDK: cdk deploy -c user_pool_id=xxxxxx.
Conclusione
L’uso di OpenAPI risulta ancora generalmente un pochino acerbo con il cloud di AWS per via di alcune limitazioni come quelle presentate precedentemente. Tuttavia le definizioni OpenAPI ben strutturate e complete portano alla semplificazione del lavoro di ingegnerizzazione e codifica di una REST API ed allo stesso tempo permettono, a tutti i membri dei team, una facile comprensione su come integrare i vari servizi.
I hope to see you again, cheerio!
