gcp_interco adapter

Overview

Model and handlers provided by this module are responsible for GCP interconnect attachment resource provisioning. This kind of GCP resource (also known as VLAN attachment) determines which Virtual Private Cloud networks can reach on-premises network through an interconnect.

Sides

Concept of interconnect attachment assumes that there are two sides:

• customer

• provider

To establish a connection between customer and provider it is required to setup 2 interconnect attachments: one on customer and one provider side. Each of them has its own name. Both interconnect attachments are coupled using a pairing key. This key is automatically generated by GCP API during customer interconnect attachment creation. VLAN ID is set for provider interconnect attachment and then propagated to customer interconnect attachment (and because of this it is impossible to have customer interconnect attachment with assigned VLAN without provider interconnect attachment).

Activation

One additional action is required for already created service to start passing traffic through it. This action is an activation. During activation BGP peering is being set up for already provisioned service.

States

GCP API uses also dedicated states enum to indicate current state of interconnect attachment service. It is used both for provider and customer interconnect attachments. This state can take one of the following values:

• UNPROVISIONED - The attachment is not ready to use yet, because turnup is not complete. Not present in most part of provisioning attempts. Sometimes can be spotted for very short time period after interconnect attachment creation has been triggered by API.

• PENDING_PARTNER - A newly-created attachment that has not yet been configured on the partner side. Mainly for newly-created standalone customer interconnect attachment waiting for corresponding provider interconnect attachment creation to be triggered.

• PARTNER_REQUEST_RECEIVED - An attachment is in the process of provisioning after second attachment was created that references it. Transient state during both customer and provider interconnect attachments creation indicates that GCP is currently performing all the operations required for this service to be successfully provisioned.

• PENDING_CUSTOMER - An attachment that is waiting for a customer to activate it. Permanent state for case with no activation that means that all required operations has been executed on GCP side and service is ready to be used but traffic is not being sent through it (because the service hasn’t been activated yet).

• ACTIVE - The attachment has been turned up and is ready to use - traffic can be send through it (permanent state).

• DEFUNCT - The attachment was deleted externally and is no longer functional (permanent state). This could be because the associated interconnect was removed or because the other side of a partner attachment was deleted.

InterconnectAttachmentHandler

InterconnectAttachmentHandler supports provisioning (CRUD actions) of provider interconnect attachment. It means that to run handler all the actions related to customer interconnect attachment must be done manually. Because of this it is required to create customer interconnect attachment and obtain a pairing key before running of the handler.

InterconnectAttachmentHandler doesnt’t support interconnect attachements pair activation. It must be done manually after provisioning of provider interconnect attachment for customer interconnect attachment.

InterconnectAttachmentHandler is aware of interconnect attachment states used by API during operations.

Read

Handler asks GCP API about interconnect attachment with given name. In case of 400 HTTP status code received from the GCP API given resource will be skipped. In case of 404 HTTP status code received from the GCP API special status PURGED will be set in the context for given interconnect attachment name. This will be consumed e.g. by create operation as input, telling that interconnect attachment with given name does not exist on GCP side.

For existing interconnect attachments obtained by GCP API call state check will be performed:

• ACTIVE: consider this resource in further processing

• UNPROVISIONED: consider this resource in further processing

• PENDING_PARTNER: invalid state - raise InvalidConnectionStateException

• PARTNER_REQUEST_RECEIVED: consider this resource in further processing

• PENDING_CUSTOMER: consider this resource in further processing

• DEFUNCT: consider this resource in further processing

Create

For creation first stage is to run read operation (done by orchestration engine logic). Then InterconnectAttachmentHandler will decide if it is possible to create new resource based on state returned by read operation:

• ACTIVE: invalid state (given resource exists, so cannot be created) - raise InvalidConnectionStateException

• UNPROVISIONED: invalid state (given resource exists, so cannot be created) - raise InvalidConnectionStateException

• PENDING_PARTNER: invalid state (given resource exists, so cannot be created) - raise InvalidConnectionStateException

• PARTNER_REQUEST_RECEIVED: invalid state (given resource exists, so cannot be created) - raise InvalidConnectionStateException

• PENDING_CUSTOMER: invalid state (given resource exists, so cannot be created) - raise InvalidConnectionStateException

• DEFUNCT: invalid state (given resource exists, so cannot be created) - raise InvalidConnectionStateException

• PURGED: create resource (because it does not exist)

Typical states transition workflow for resource creation is:

Orchestartor	Provider IA	Customer IA
	-	PENDING_PARTNER
create ->	-	PENDING_PARTNER
	(UNPROVISIONED / STATE_UNSPECIFIED)	PENDING_PARTNER
	PARTNER_REQUEST_RECEIVED	PARTNER_REQUEST_RECEIVED
(after few seconds)	PENDING_CUSTOMER	PENDING_CUSTOMER

PENDING_PARTNER is a state of customer interconnect attachment which has been created and is waiting for provider interconnect attachment to be created and paired. Mentioned transition to UNPROVISIONED / STATE_UNSPECIFIED may occur but during tests executions has not been observed. GCP also uses something like STATE_UNSPECIFIED which can be treated as null value.

Then service can be activated. It should be done manually for customer interconnect attachment. During activation state transition PENDING_CUSTOMER -> ACTIVE should have place without any transient state. Reverse transition should take place for deactivation.

Update

For update first stage is to run read operation (done by orchestration engine logic). It is required to have existing interconnect attachment in some of permanent working states, so InterconnectAttachmentHandler reactions are:

• ACTIVE: run update (interconnect attachment activated and can bu update)

• UNPROVISIONED: update cannot be performed in this state because resource has not been configured yet on GCP side - skip resource

• PENDING_PARTNER: invalid state (cannot be present for provider interconnect attachment) - raise InvalidConnectionStateException

• PARTNER_REQUEST_RECEIVED: update cannot be performed in this state because resource is already being configured on GCP side - skip resource

• PENDING_CUSTOMER: run update (interconnect attachment not activated but provisioned successfully on GCP side - can be updated)

• DEFUNCT: invalid state (cannot update broken interconnect attachment) - raise InvalidConnectionStateException

• PURGED: invalid state (cannot update non-existent interconnect attachment) - raise InvalidConnectionStateException

For update it is important to handle transient states properly. Attempt of sending update request for interconnect attachment being in transient state (e.g. PARTNER_REQUEST_RECEIVED) will result in HTTP 400 response with message: “Resource not ready”. So, skipping resource which is in transient state will force an orchestrator to retry attempt. In next attempt interconnect may be in a permanent state and whole update may succeed.

Delete

For creation first stage is to run read operation (done by orchestration engine logic). Then InterconnectAttachmentHandler will decide if it is possible to delete existing resource based on state returned by read operation:

• ACTIVE: resource is present - send delete request to API

• UNPROVISIONED: resource is present - send delete request to API

• PENDING_PARTNER: invalid state (cannot be present for provider interconnect attachment) - raise InvalidConnectionStateException,

• PARTNER_REQUEST_RECEIVED: resource is present - send delete request to API

• PENDING_CUSTOMER: resource is present - send delete request to API

• DEFUNCT: resource is present - send delete request to API

• PURGED: resource is not present - do nothing

No additional state transition of provider interconnect attachment which is being deleted is expected. For customer interconnect attachment state transition should take place: PENDING_CUSTOMER / ACTIVE -> DEFUNCT. Last state means that this customer interconnect attachment is no longer functional because corresponding provider interconnect attachment has been deleted.

InterconnectAttachmentStateHandler

InterconnectAttachmentStateHandler handler with its resource InterconnectAttachmentState have been implemented to give a possibility to do GCP interconnect attachment state based verification of given GCP Inmanta deployment.

The idea is to include InterconnectAttachmentState either in the same model like GCP interconnect attachment or in the model of separate deployment. This entity has 3 list as fields, they are:

• desired - by default:

  • ACTIVE

• failed - by default:

  • DEFUNCT

  • PURGED

• skipped - by default:

  • UNPROVISIONED

  • PENDING_PARTNER

  • PARTNER_REQUEST_RECEIVED

  • PENDING_CUSTOMER

InterconnectAttachmentStateHandler has only read method implemented. This method reads an interconnect attachment state then checks which list contains this state and makes a decision based of this information:

• current interconnect attachment state is in desired list - do nothing because provisioning process has been completed successfully

• current interconnect attachment state is in failed list - raise an exception to fail whole deployment - this will indicate failure of provisioning process

• current interconnect attachment state is in skipped list - skip resource and retry status checking

So InterconnectAttachmentState may be use for state verification of given interconnect attachment and also whole interconnect attachment deployment.

Examples

Examples directory contains 3 GCP CF models which can be deployed using Inmanta orchestartor. There are:

• interconnect_attachment.cf - basic model for interconnect attachment creation

• interconnect_attachment_state.cf - basic model for interconnect attachment state verification

• interconnect_attachment_state_2.cf - basic model for interconnect attachment state verification with custom states definition.

Tests

Tests consist of components, handlers, state reactions and end to end tests. They can be run on either on mocked API (default behaviour) or on real GCP API

1. Setup a virtual env

   virtualenv inmanta-test -p python3
   source inmanta-test/bin/activate
   
   pip install -r requirements.dev.txt
   pip install -r requirements.txt
   

2. Set environmental variables

    export INMANTA_MODULE_REPO="git@github.com:inmanta"
    export GCP_CLOUDCONNECT_CUSTOMER="/path/to/customer/credentials/file.json"
    export GCP_CLOUDCONNECT_PROVIDER="/path/to/provider/credentials/file.json"
   

3. Run tests

   On the mock (default):

   pytest --venv="absolute/path/to/virtualenv/inmanta-test"
   

   On real GCP API:

   pytest --venv="absolute/path/to/virtualenv/inmanta-test" --real
   

External documentation

• https://cloud.google.com/interconnect/docs/concepts/partner-overview

• https://cloud.google.com/interconnect/docs/how-to/dedicated/creating-vlan-attachments

• https://cloud.google.com/compute/docs/reference/rest/v1/interconnectAttachments

• Module gcp_interco
• Changelog