├── .gitignore ├── governance ├── IMPLEMENTERS.md ├── MAINTAINING_ORGS.md ├── STEERING_COMMITTEE.md ├── MAINTAINERS.md ├── SECURITY_AND_OPERATIONAL_EXCELLENCE.md └── GOVERNANCE_MODEL.md ├── .github └── CODEOWNERS ├── NOTICE ├── CODE_OF_CONDUCT.md ├── README.md ├── AUTHORS ├── connection-coordinator ├── paths │ ├── providers.yaml │ ├── interconnects.yaml │ ├── environments.yaml │ ├── macseckeys.yaml │ ├── channels.yaml │ ├── features.yaml │ ├── issues.yaml │ └── connections.yaml ├── schemas │ ├── common.yaml │ ├── macseckey.yaml │ ├── provider.yaml │ ├── interconnect.yaml │ ├── feature.yaml │ ├── channel.yaml │ ├── environment.yaml │ ├── issues.yaml │ └── connection.yaml ├── parameters │ └── _index.yaml ├── openapi.yaml └── docs │ └── ConnectionCoordinatorAPI.md ├── CONTRIBUTING.md └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store -------------------------------------------------------------------------------- /governance/IMPLEMENTERS.md: -------------------------------------------------------------------------------- 1 | ## Implementers 2 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @bpescato-amazon 2 | * @VTWoods 3 | -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 2 | -------------------------------------------------------------------------------- /governance/MAINTAINING_ORGS.md: -------------------------------------------------------------------------------- 1 | ## Maintaining Organizations 2 | - Amazon Web Services 3 | - Google 4 | -------------------------------------------------------------------------------- /governance/STEERING_COMMITTEE.md: -------------------------------------------------------------------------------- 1 | # Steering Committee 2 | - Amazon Web Services 3 | - Brian Pescatore (@bpescato-amazon) 4 | - Google 5 | - Mike Woods (@vtwoods) -------------------------------------------------------------------------------- /governance/MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | 3 | ## Amazon Web Services 4 | 1. Brian Pescatore (@bpescato-amazon) 5 | 2. Ilya Kosolapov 6 | 3. Pratik Bartakke 7 | 8 | ## Google 9 | 1. Mike Woods (@vtwoods) 10 | 2. Dave Karwowski 11 | 3. Ethan Hodges -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | ## Code of Conduct 2 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 3 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 4 | opensource-codeofconduct@amazon.com with any additional questions or comments. 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Connection Coordinator API Specification 2 | 3 | Describes the OpenAPI 3.0 specification of the symmetric API to be used to coordinate managed L3 connectivity. 4 | 5 | ## Governance 6 | 7 | The specification is governed under the specifics as laid out in the [GOVERNANCE MODEL](governance/GOVERNANCE_MODEL.md). 8 | 9 | 10 | ## License 11 | 12 | This project is licensed under the Apache-2.0 License. 13 | 14 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | # This is the list of the Connection Coordinator API Specification's initial authors. 2 | # 3 | # This does not necessarily list everyone who has contributed code, 4 | # especially since many employees of one corporation may be contributing. 5 | # To see the full list of contributors, see the revision history in 6 | # source control. 7 | 8 | Amazon Web Services 9 | Google 10 | Mike Woods 11 | Brian Pescatore 12 | Dave Karwowski 13 | Ilya Kosolapov 14 | Judy Issa 15 | Santiago Riesco 16 | Kaitlin Sem 17 | Pratik Bartakke 18 | Ethan Hodges 19 | Sandeep Perumalla 20 | -------------------------------------------------------------------------------- /connection-coordinator/paths/providers.yaml: -------------------------------------------------------------------------------- 1 | AllProviders: 2 | get: 3 | description: Get details on a specific provider managed by this server. 4 | operationId: ListProviders 5 | responses: 6 | default: 7 | content: 8 | application/json: 9 | schema: 10 | $ref: "../schemas/provider.yaml#/ListProvidersResponse" 11 | description: Successful operation 12 | security: [] 13 | tags: 14 | - Providers 15 | OneProvider: 16 | get: 17 | description: Get details on a specific provider managed by this server. 18 | operationId: GetProvider 19 | parameters: 20 | - $ref: "../parameters/_index.yaml#/parameters/provider" 21 | responses: 22 | default: 23 | content: 24 | application/json: 25 | schema: 26 | $ref: "../schemas/provider.yaml#/Provider" 27 | description: Successful operation 28 | security: [] 29 | tags: 30 | - Providers -------------------------------------------------------------------------------- /connection-coordinator/schemas/common.yaml: -------------------------------------------------------------------------------- 1 | AdminState: 2 | description: | 3 | Enum that describes the admin state of a resource. 4 | ADMIN_STATE_ENABLED - A provider has administratively enabled a resource. 5 | ADMIN_STATE_DISABLED - A provider has administratively disabled a resource. 6 | enum: 7 | - ADMIN_STATE_ENABLED 8 | - ADMIN_STATE_DISABLED 9 | type: string 10 | 11 | VerificationState: 12 | description: |- 13 | Enum that describes the verification state of a resource. 14 | VERIFICATION_STATE_UNVERIFIED - Verification is pending and not ready for production traffic. 15 | VERIFICATION_STATE_VERIFIED - Verification is complete and ready for production traffic. 16 | enum: 17 | - VERIFICATION_STATE_UNVERIFIED 18 | - VERIFICATION_STATE_VERIFIED 19 | type: string 20 | 21 | ProvisioningState: 22 | description: |- 23 | Enum that describes the provisioning state of a resource. 24 | PROVISIONING_STATE_PENDING: 25 | 1. Feature is created and parameters are reserved. 26 | 27 | PROVISIONING_STATE_FINAL: 28 | 1. Configuration has propagated fully to the provider's infrastructure. 29 | 2. Customer may send production traffic between providers using the 30 | feature. 31 | enum: 32 | - PROVISIONING_STATE_PENDING 33 | - PROVISIONING_STATE_FINAL 34 | type: string 35 | 36 | Empty: 37 | description: |- 38 | A generic empty message that you can re-use to avoid defining duplicated 39 | empty messages in your APIs. 40 | type: object -------------------------------------------------------------------------------- /connection-coordinator/schemas/macseckey.yaml: -------------------------------------------------------------------------------- 1 | MacSecKey: 2 | description: |- 3 | MacSecKey resources contain the necessary details to setup MACsec keys 4 | on the Channel object. 5 | 6 | A Channel is limited to 2 MacSecKey objects at any one time, and amongst 7 | the `N` Channels on the respective parent Interconnect, the limit is `N+1` 8 | 9 | When creating the MacSecKey, the `startTime` on the created object MUST 10 | be set by the server to the current time when the request was accepted. 11 | example: 12 | name: name 13 | cak: MACsec CAK 14 | ckn: MACsec CKN 15 | startTime: 2000-01-23T04:56:07.000+00:00 16 | active: true 17 | properties: 18 | name: 19 | description: Identifier. A unique identifer for the macSecKey resource. 20 | type: string 21 | cak: 22 | description: MACsec protocol CAK. 23 | type: string 24 | ckn: 25 | description: MACsec protocol CKN. 26 | type: string 27 | startTime: 28 | description: Timestamp indicating when this MacSecKey was created. 29 | format: date-time 30 | type: string 31 | readOnly: true 32 | active: 33 | description: |- 34 | Indicates that this key is active on the respective `channel`. Only one 35 | macSecKey can be `active=true` on a `channel` at a given time. 36 | 37 | While `active=true`, this macSecKey cannot be deleted. 38 | type: boolean 39 | readOnly: true 40 | 41 | ListMacSecKeysResponse: 42 | description: Response for obtaining multiple MacSecKey resources 43 | properties: 44 | macSecKeys: 45 | description: The macSecKeys for the respective Channel 46 | items: 47 | $ref: "#/MacSecKey" 48 | type: array 49 | type: object 50 | -------------------------------------------------------------------------------- /connection-coordinator/paths/interconnects.yaml: -------------------------------------------------------------------------------- 1 | AllInterconnects: 2 | get: 3 | description: List all interconnects associated with a specified environment. 4 | operationId: ListInterconnects 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - $ref: "../parameters/_index.yaml#/parameters/environment" 8 | - description: |- 9 | The maximum number of interconnects to return. The service may return fewer 10 | than this value. 11 | explode: true 12 | in: query 13 | name: pageSize 14 | required: false 15 | schema: 16 | format: int32 17 | type: integer 18 | style: form 19 | - description: |- 20 | A page token, received from a previous `ListInterconnects` call. 21 | Provide this to retrieve the subsequent page. 22 | 23 | When paginating, all other parameters provided to `ListInterconnects` must 24 | match the call that provided the page token. 25 | explode: true 26 | in: query 27 | name: pageToken 28 | required: false 29 | schema: 30 | type: string 31 | style: form 32 | responses: 33 | default: 34 | content: 35 | application/json: 36 | schema: 37 | $ref: "../schemas/interconnect.yaml#/ListInterconnectsResponse" 38 | description: Successful operation 39 | security: [] 40 | tags: 41 | - Interconnects 42 | OneInterconnect: 43 | get: 44 | description: Get details about a specific interconnect. 45 | operationId: GetInterconnect 46 | parameters: 47 | - $ref: "../parameters/_index.yaml#/parameters/provider" 48 | - $ref: "../parameters/_index.yaml#/parameters/environment" 49 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 50 | responses: 51 | default: 52 | content: 53 | application/json: 54 | schema: 55 | $ref: "../schemas/interconnect.yaml#/Interconnect" 56 | description: Successful operation 57 | security: [] 58 | tags: 59 | - Interconnects 60 | -------------------------------------------------------------------------------- /connection-coordinator/schemas/provider.yaml: -------------------------------------------------------------------------------- 1 | Provider: 2 | description: |- 3 | Provider resources encapsulate all information that describe the 4 | relationship between a remote provider and a server provider. 5 | 6 | When a remote provider calls this API, the provider should always reference 7 | their assigned provider id. Provider IDs are globally unique, and stored in 8 | this specification's opensource repository. This allows a remote provider to 9 | have access to multiple provider IDs as business relationship change over 10 | time. 11 | 12 | For example, if we have two providers (ProviderA, ProviderB) who are 13 | coordinating connections with this API, when ProviderA (remote provider) 14 | calls this API hosted by ProviderB (server provider), their requests will 15 | always be prefixed by: 16 | 17 | Prefix: providers/ 18 | 19 | If the server provider has decided that ProviderA's credentials allow them to 20 | access additional credentials (through something like an acquisition), 21 | ProviderA may access all resources under ProviderC. 22 | 23 | ProviderB must also allow ProviderA to access the server's provider resource 24 | (providers/). This provides ProviderA with access to relevant 25 | information about the server provider (such as display names). 26 | example: 27 | displayName: displayName 28 | name: name 29 | properties: 30 | name: 31 | description: |- 32 | Identifier. Unique identifier for a Provider resource. 33 | 34 | Every provider that supports the cloud connectivity API will receive a 35 | centrally managed provider ID, stored alongside this specification in the 36 | opensource project, that uniquely identifies them. When accessing a remote 37 | cloud connectivity server, the provider will use their provider ID to 38 | request and create resources within the remote server. 39 | type: string 40 | displayName: 41 | description: |- 42 | Output only. Provider name suitable for display to end users. 43 | 44 | Example: Amazon Web Services, Google Cloud Platform, Microsoft Azure, etc 45 | readOnly: true 46 | type: string 47 | type: object 48 | 49 | ListProvidersResponse: 50 | description: Response for obtaining multiple provider resources. 51 | example: 52 | providers: 53 | - displayName: displayName 54 | name: name 55 | - displayName: displayName 56 | name: name 57 | nextPageToken: nextPageToken 58 | properties: 59 | environments: 60 | description: The providers known to the remote. 61 | items: 62 | $ref: "#/Provider" 63 | type: array 64 | nextPageToken: 65 | description: |- 66 | A token, which can be sent as `page_token` to retrieve the next page. 67 | If this field is omitted, there are no subsequent pages. 68 | type: string 69 | type: object 70 | -------------------------------------------------------------------------------- /connection-coordinator/paths/environments.yaml: -------------------------------------------------------------------------------- 1 | AllEnvironments: 2 | get: 3 | description: List all environments associated with a CSP. 4 | operationId: ListEnvironments 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - description: |- 8 | The maximum number of environments to return. The service may return fewer 9 | than this value. 10 | explode: true 11 | in: query 12 | name: pageSize 13 | required: false 14 | schema: 15 | format: int32 16 | type: integer 17 | style: form 18 | - description: |- 19 | A page token, received from a previous `ListEnvironments` call. 20 | Provide this to retrieve the subsequent page. 21 | 22 | When paginating, all other parameters provided to `ListEnvironments` must 23 | match the call that provided the page token. 24 | explode: true 25 | in: query 26 | name: pageToken 27 | required: false 28 | schema: 29 | type: string 30 | style: form 31 | responses: 32 | default: 33 | content: 34 | application/json: 35 | schema: 36 | $ref: "../schemas/environment.yaml#/ListEnvironmentsResponse" 37 | description: Successful operation 38 | security: [] 39 | tags: 40 | - Environments 41 | OneEnvironment: 42 | get: 43 | description: Get details about a specific environment. 44 | operationId: GetEnvironment 45 | parameters: 46 | - $ref: "../parameters/_index.yaml#/parameters/provider" 47 | - $ref: "../parameters/_index.yaml#/parameters/environment" 48 | responses: 49 | default: 50 | content: 51 | application/json: 52 | schema: 53 | $ref: "../schemas/environment.yaml#/Environment" 54 | description: Successful operation 55 | security: [] 56 | tags: 57 | - Environments 58 | ConfirmActivationKey: 59 | post: 60 | description: |- 61 | Allows a provider to validate the authenticity of an activation key before 62 | creating a connection associated with it. 63 | 64 | FUTURE: In the future, we may allow providers to convey additional 65 | provisioning information excluded from the activation key in their 66 | response. 67 | operationId: ConfirmActivationKey 68 | parameters: 69 | - $ref: "../parameters/_index.yaml#/parameters/provider" 70 | - $ref: "../parameters/_index.yaml#/parameters/environment" 71 | requestBody: 72 | content: 73 | application/json: 74 | schema: 75 | $ref: "../schemas/environment.yaml#/ConfirmActivationKeyRequest" 76 | description: The request body. 77 | responses: 78 | default: 79 | content: 80 | application/json: 81 | schema: 82 | $ref: "../schemas/environment.yaml#/ConfirmActivationKeyResponse" 83 | description: Successful operation 84 | security: [] 85 | tags: 86 | - Environments 87 | -------------------------------------------------------------------------------- /connection-coordinator/parameters/_index.yaml: -------------------------------------------------------------------------------- 1 | parameters: 2 | provider: 3 | description: Resource ID segment making up resource `name`. 4 | explode: false 5 | in: path 6 | name: provider 7 | required: true 8 | schema: 9 | type: string 10 | style: simple 11 | 12 | environment: 13 | description: Resource ID segment making up resource `name`. 14 | explode: false 15 | in: path 16 | name: environment 17 | required: true 18 | schema: 19 | type: string 20 | style: simple 21 | 22 | interconnect: 23 | description: Resource ID segment making up resource `name`. 24 | explode: false 25 | in: path 26 | name: interconnect 27 | required: true 28 | schema: 29 | type: string 30 | style: simple 31 | 32 | channel: 33 | description: Resource ID segment making up resource `name`. 34 | explode: false 35 | in: path 36 | name: channel 37 | required: true 38 | schema: 39 | type: string 40 | style: simple 41 | 42 | connection: 43 | description: Resource ID segment making up resource `name`. 44 | explode: false 45 | in: path 46 | name: connection 47 | required: true 48 | schema: 49 | type: string 50 | style: simple 51 | 52 | feature: 53 | description: Resource ID segment making up resource `name`. 54 | explode: false 55 | in: path 56 | name: feature 57 | required: true 58 | schema: 59 | type: string 60 | style: simple 61 | 62 | macSecKey: 63 | description: Resource ID segment making up resource `name`. 64 | explode: false 65 | in: path 66 | name: macSecKey 67 | required: true 68 | schema: 69 | type: string 70 | style: simple 71 | 72 | issue: 73 | description: Resource ID segment making up resource `name`. 74 | explode: false 75 | in: path 76 | name: issue 77 | required: true 78 | schema: 79 | type: string 80 | style: simple 81 | 82 | alt: 83 | description: Data format for response. 84 | explode: true 85 | in: query 86 | name: $alt 87 | required: false 88 | schema: 89 | default: json 90 | enum: 91 | - json 92 | - media 93 | - proto 94 | type: string 95 | style: form 96 | 97 | callback: 98 | description: JSONP 99 | explode: true 100 | in: query 101 | name: $callback 102 | required: false 103 | schema: 104 | type: string 105 | style: form 106 | 107 | prettyPrint: 108 | description: Returns response with indentations and line breaks. 109 | explode: true 110 | in: query 111 | name: $prettyPrint 112 | required: false 113 | schema: 114 | default: true 115 | type: boolean 116 | style: form 117 | 118 | _.xgafv: 119 | description: V1 error format. 120 | explode: true 121 | in: query 122 | name: $.xgafv 123 | required: false 124 | schema: 125 | enum: 126 | - "1" 127 | - "2" 128 | type: string 129 | style: form -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing Guidelines 2 | 3 | Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional 4 | documentation, we greatly value feedback and contributions from our community. 5 | 6 | Please read through this document before submitting any issues or pull requests to ensure we have all the necessary 7 | information to effectively respond to your bug report or contribution. 8 | 9 | Also, please note that any and all contributions to this project are governed by the [GOVERNANCE MODEL](governance/GOVERNANCE_MODEL.md). Any requests for modification that do not meet the criteria as outlined there, will not be considered. 10 | 11 | ## Reporting Bugs/Feature Requests 12 | 13 | We welcome you to use the GitHub issue tracker to report bugs or suggest features. 14 | 15 | When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already 16 | reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: 17 | 18 | * A reproducible test case or series of steps 19 | * The version of our code being used 20 | * Any modifications you've made relevant to the bug 21 | * Anything unusual about your environment or deployment 22 | 23 | 24 | ## Contributing via Pull Requests 25 | Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: 26 | 27 | 1. You are working against the latest source on the *main* branch. 28 | 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already. 29 | 3. You open an issue to discuss any significant work - we would hate for your time to be wasted. 30 | 31 | To send us a pull request, please: 32 | 33 | 1. Fork the repository. 34 | 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. 35 | 3. Ensure local tests pass. 36 | 4. Commit to your fork using clear commit messages. 37 | 5. Send us a pull request, answering any default questions in the pull request interface. 38 | 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. 39 | 40 | GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and 41 | [creating a pull request](https://help.github.com/articles/creating-a-pull-request/). 42 | 43 | 44 | ## Finding contributions to work on 45 | Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start. 46 | 47 | 48 | ## Code of Conduct 49 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 50 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 51 | opensource-codeofconduct@amazon.com with any additional questions or comments. 52 | 53 | 54 | ## Licensing 55 | 56 | See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. 57 | -------------------------------------------------------------------------------- /connection-coordinator/paths/macseckeys.yaml: -------------------------------------------------------------------------------- 1 | AllMacSecKeys: 2 | post: 3 | description: Create a new MACsec key on the channel 4 | operationId: CreateMacSecKey 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - $ref: "../parameters/_index.yaml#/parameters/environment" 8 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 9 | - $ref: "../parameters/_index.yaml#/parameters/channel" 10 | - description: |- 11 | Required. The ID to use for the macSecKey, which will become the final component of 12 | the connection's resource name. 13 | explode: false 14 | in: query 15 | name: macSecKeyId 16 | required: true 17 | schema: 18 | type: string 19 | style: form 20 | requestBody: 21 | content: 22 | application/json: 23 | example: 24 | name: name 25 | cak: MACsec CAK 26 | ckn: MACsec CKN 27 | schema: 28 | $ref: "../schemas/macseckey.yaml#/MacSecKey" 29 | description: The request body. 30 | 31 | responses: 32 | default: 33 | content: 34 | application/json: 35 | schema: 36 | $ref: "../schemas/macseckey.yaml#/MacSecKey" 37 | description: Successful operation 38 | security: [] 39 | tags: 40 | - MacSecKey 41 | get: 42 | description: List all the MACsec keys associated with the channel 43 | operationId: ListMacSecKeys 44 | parameters: 45 | - $ref: "../parameters/_index.yaml#/parameters/provider" 46 | - $ref: "../parameters/_index.yaml#/parameters/environment" 47 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 48 | - $ref: "../parameters/_index.yaml#/parameters/channel" 49 | responses: 50 | default: 51 | content: 52 | application/json: 53 | schema: 54 | $ref: "../schemas/macseckey.yaml#/ListMacSecKeysResponse" 55 | description: Successful operation 56 | security: [] 57 | tags: 58 | - MacSecKey 59 | 60 | OneMacSecKey: 61 | get: 62 | description: Get the specific MACsec key associated with the channel 63 | operationId: GetMacSecKey 64 | parameters: 65 | - $ref: "../parameters/_index.yaml#/parameters/provider" 66 | - $ref: "../parameters/_index.yaml#/parameters/environment" 67 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 68 | - $ref: "../parameters/_index.yaml#/parameters/channel" 69 | - $ref: "../parameters/_index.yaml#/parameters/macSecKey" 70 | responses: 71 | default: 72 | content: 73 | application/json: 74 | schema: 75 | $ref: "../schemas/macseckey.yaml#/MacSecKey" 76 | description: Successful operation 77 | security: [] 78 | tags: 79 | - MacSecKey 80 | delete: 81 | description: Delete the specific MACsec key associated with the channel 82 | operationId: DeleteMacSecKey 83 | parameters: 84 | - $ref: "../parameters/_index.yaml#/parameters/provider" 85 | - $ref: "../parameters/_index.yaml#/parameters/environment" 86 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 87 | - $ref: "../parameters/_index.yaml#/parameters/channel" 88 | - $ref: "../parameters/_index.yaml#/parameters/macSecKey" 89 | responses: 90 | default: 91 | content: 92 | application/json: 93 | schema: 94 | $ref: "../schemas/common.yaml#/Empty" 95 | description: Successful operation 96 | security: [] 97 | tags: 98 | - MacSecKey 99 | 100 | -------------------------------------------------------------------------------- /connection-coordinator/paths/channels.yaml: -------------------------------------------------------------------------------- 1 | AllChannels: 2 | get: 3 | description: List all channels associated with an interconnect. 4 | operationId: ListChannels 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - $ref: "../parameters/_index.yaml#/parameters/environment" 8 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 9 | - description: |- 10 | The maximum number of channels to return. The service may return fewer 11 | than this value. 12 | explode: true 13 | in: query 14 | name: pageSize 15 | required: false 16 | schema: 17 | format: int32 18 | type: integer 19 | style: form 20 | - description: |- 21 | A page token, received from a previous `ListChannels` call. 22 | Provide this to retrieve the subsequent page. 23 | 24 | When paginating, all other parameters provided to `ListChannels` must 25 | match the call that provided the page token. 26 | explode: true 27 | in: query 28 | name: pageToken 29 | required: false 30 | schema: 31 | type: string 32 | style: form 33 | responses: 34 | default: 35 | content: 36 | application/json: 37 | schema: 38 | $ref: "../schemas/channel.yaml#/ListChannelsResponse" 39 | description: Successful operation 40 | security: [] 41 | tags: 42 | - Channels 43 | OneChannel: 44 | get: 45 | description: Get details about a specific channel. 46 | operationId: GetChannel 47 | parameters: 48 | - $ref: "../parameters/_index.yaml#/parameters/provider" 49 | - $ref: "../parameters/_index.yaml#/parameters/environment" 50 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 51 | - $ref: "../parameters/_index.yaml#/parameters/channel" 52 | responses: 53 | default: 54 | content: 55 | application/json: 56 | schema: 57 | $ref: "../schemas/channel.yaml#/Channel" 58 | description: Successful operation 59 | security: [] 60 | tags: 61 | - Channels 62 | NotifyMaintenance: 63 | post: 64 | description: |- 65 | Notify a remote provider that maintenance events associated with a channel 66 | have been modified. 67 | operationId: NotifyMaintenance 68 | parameters: 69 | - $ref: "../parameters/_index.yaml#/parameters/provider" 70 | - $ref: "../parameters/_index.yaml#/parameters/environment" 71 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 72 | - $ref: "../parameters/_index.yaml#/parameters/channel" 73 | requestBody: 74 | content: 75 | application/json: 76 | schema: 77 | $ref: "../schemas/channel.yaml#/NotifyMaintenanceRequest" 78 | description: The request body. 79 | responses: 80 | default: 81 | content: 82 | application/json: 83 | schema: 84 | $ref: "../schemas/common.yaml#/Empty" 85 | description: Successful operation 86 | security: [] 87 | tags: 88 | - Channels 89 | GetMaintenanceEvents: 90 | get: 91 | description: Get all maintenance events associated with a channel. 92 | operationId: GetMaintenanceEvents 93 | parameters: 94 | - $ref: "../parameters/_index.yaml#/parameters/provider" 95 | - $ref: "../parameters/_index.yaml#/parameters/environment" 96 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 97 | - $ref: "../parameters/_index.yaml#/parameters/channel" 98 | responses: 99 | default: 100 | content: 101 | application/json: 102 | schema: 103 | $ref: "../schemas/channel.yaml#/GetMaintenanceEventsResponse" 104 | description: Successful operation 105 | security: [] 106 | tags: 107 | - Channels 108 | -------------------------------------------------------------------------------- /connection-coordinator/schemas/interconnect.yaml: -------------------------------------------------------------------------------- 1 | Interconnect: 2 | description: |- 3 | Interconnect resources describe a group of redundant physical links between 4 | providers that are used to provision redundant connections for a customer. 5 | 6 | Interconnect resource 'name' and 'supported_connection_size_mbps' are 7 | exchanged between providers at setup time. This allows both providers to 8 | call each other's respective APIs with a shared resource key and lookup 9 | additional dynamic details about the connectivity. 10 | 11 | All other fields are controlled by the server provider. 12 | example: 13 | supportedFeatures: 14 | - FEATURE_TYPE_L3_BASE 15 | - FEATURE_TYPE_L3_BASE 16 | name: name 17 | state: "" 18 | supportedConnectionSizeMbps: 19 | - 0 20 | - 0 21 | maxBandwidthMbps: 6 22 | properties: 23 | name: 24 | description: Identifier. Unique identifier for the Interconnect resource. 25 | type: string 26 | supportedConnectionSizeMbps: 27 | description: |- 28 | Output only. A list of Mbps connection sizes supported on the interconnect. This field 29 | must contain all supported connection sizes defined in the parent 30 | environment but may include additional sizes specific to this interconnect. 31 | items: 32 | format: int32 33 | type: integer 34 | readOnly: true 35 | type: array 36 | supportedFeatures: 37 | description: |- 38 | Output only. A list of features supported by the interconnect. Any child connections of 39 | this interconnect may have the specified features configured on them. This 40 | field must contain all supported features defined in the parent 41 | environment but may include additional features specific to this 42 | interconnect. 43 | items: 44 | $ref: "feature.yaml#/FeatureType" 45 | readOnly: true 46 | type: array 47 | state: 48 | allOf: 49 | - $ref: "#/InterconnectState" 50 | description: |- 51 | Output only. The operational state of the interconnect used to control connection 52 | provisioning. 53 | readOnly: true 54 | maxBandwidthMbps: 55 | description: |- 56 | Output only. Specified the aggregate connection bandwidth that can be configured on the 57 | interconnect. Generally this value matches the minimum channel bandwidth 58 | across all channels associated with the interconnect. However, this field 59 | allows a a provider to limit the total connection bandwidth below the 60 | aggregate physical capacity. 61 | 62 | If not respected by the remote provider, connection creation that exceeds 63 | this threshold will fail. 64 | format: int32 65 | readOnly: true 66 | type: integer 67 | type: object 68 | InterconnectState: 69 | description: |- 70 | Enum that describes the state of an Interconnect. 71 | INTERCONNECT_STATE_PENDING - Provisioning is pending and not ready for production traffic. 72 | INTERCONNECT_STATE_ACTIVE - Provisioning is complete and ready for production traffic. 73 | INTERCONNECT_STATE_CLOSED - Functional for current customers but closed to new connections. 74 | enum: 75 | - INTERCONNECT_STATE_PENDING 76 | - INTERCONNECT_STATE_ACTIVE 77 | - INTERCONNECT_STATE_CLOSED 78 | type: string 79 | 80 | ListInterconnectsResponse: 81 | description: Response for obtaining multiple interconnect resources. 82 | example: 83 | interconnects: 84 | - supportedFeatures: 85 | - FEATURE_TYPE_L3_BASE 86 | - FEATURE_TYPE_L3_BASE 87 | name: name 88 | state: "" 89 | supportedConnectionSizeMbps: 90 | - 0 91 | - 0 92 | maxBandwidthMbps: 6 93 | - supportedFeatures: 94 | - FEATURE_TYPE_L3_BASE 95 | - FEATURE_TYPE_L3_BASE 96 | name: name 97 | state: "" 98 | supportedConnectionSizeMbps: 99 | - 0 100 | - 0 101 | maxBandwidthMbps: 6 102 | nextPageToken: nextPageToken 103 | properties: 104 | interconnects: 105 | description: The interconnects from the specified provider. 106 | items: 107 | $ref: "#/Interconnect" 108 | type: array 109 | nextPageToken: 110 | description: |- 111 | A token, which can be sent as `page_token` to retrieve the next page. 112 | If this field is omitted, there are no subsequent pages. 113 | type: string 114 | type: object -------------------------------------------------------------------------------- /connection-coordinator/openapi.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.3 2 | info: 3 | description: "" 4 | title: Connection Coordinator API Specification 5 | version: v1 6 | servers: 7 | - url: / 8 | paths: 9 | /providers: 10 | $ref: paths/providers.yaml#/AllProviders 11 | /providers/{provider}: 12 | $ref: paths/providers.yaml#/OneProvider 13 | /providers/{provider}/environments: 14 | $ref: paths/environments.yaml#/AllEnvironments 15 | /providers/{provider}/environments/{environment}: 16 | $ref: paths/environments.yaml#/OneEnvironment 17 | /providers/{provider}/environments/{environment}/ConfirmActivationKey: 18 | $ref: paths/environments.yaml#/ConfirmActivationKey 19 | /providers/{provider}/environments/{environment}/interconnects: 20 | $ref: paths/interconnects.yaml#/AllInterconnects 21 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}: 22 | $ref: paths/interconnects.yaml#/OneInterconnect 23 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/channels: 24 | $ref: paths/channels.yaml#/AllChannels 25 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/channels/{channel}: 26 | $ref: paths/channels.yaml#/OneChannel 27 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/channels/{channel}/NotifyMaintenance: 28 | $ref: paths/channels.yaml#/NotifyMaintenance 29 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/channels/{channel}/maintenanceEvents: 30 | $ref: paths/channels.yaml#/GetMaintenanceEvents 31 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/channels/{channel}/macSecKeys: 32 | $ref: paths/macseckeys.yaml#/AllMacSecKeys 33 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/channels/{channel}/macSecKeys/{macSecKey}: 34 | $ref: paths/macseckeys.yaml#/OneMacSecKey 35 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/connections: 36 | $ref: paths/connections.yaml#/AllConnections 37 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/connections/{connection}: 38 | $ref: paths/connections.yaml#/OneConnection 39 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/connections/{connection}/GenerateFeatureGuidance: 40 | $ref: paths/connections.yaml#/GenerateFeatureGuidance 41 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/connections/{connection}/NotifyConnectionStatus: 42 | $ref: paths/connections.yaml#/NotifyConnectionStatus 43 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/connections/{connection}/features: 44 | $ref: paths/features.yaml#/AllFeatures 45 | /providers/{provider}/environments/{environment}/interconnects/{interconnect}/connections/{connection}/features/{feature}: 46 | $ref: paths/features.yaml#/OneFeature 47 | /providers/{provider}/issues: 48 | $ref: paths/issues.yaml#/AllIssues 49 | /providers/{provider}/issues/{issue}: 50 | $ref: paths/issues.yaml#/OneIssue 51 | /providers/{provider}/issues/{issue}/Close: 52 | $ref: paths/issues.yaml#/CloseIssue 53 | /providers/{provider}/issues/{issue}/comments: 54 | $ref: paths/issues.yaml#/ListComments 55 | /providers/{provider}/issues/{issue}/AddComment: 56 | $ref: paths/issues.yaml#/AddComment 57 | components: 58 | schemas: 59 | Provider: 60 | $ref: schemas/provider.yaml#/Provider 61 | Environment: 62 | $ref: schemas/environment.yaml#/Environment 63 | Interconnect: 64 | $ref: schemas/interconnect.yaml#/Interconnect 65 | Channel: 66 | $ref: schemas/channel.yaml#/Channel 67 | Connection: 68 | $ref: schemas/connection.yaml#/Connection 69 | Feature: 70 | $ref: schemas/feature.yaml#/Feature 71 | MacSecKey: 72 | $ref: schemas/macseckey.yaml#/MacSecKey 73 | Issue: 74 | $ref: schemas/issues.yaml#/Issue 75 | parameters: 76 | provider: 77 | $ref: parameters/_index.yaml#/parameters/provider 78 | environment: 79 | $ref: parameters/_index.yaml#/parameters/environment 80 | interconnect: 81 | $ref: parameters/_index.yaml#/parameters/interconnect 82 | channel: 83 | $ref: parameters/_index.yaml#/parameters/channel 84 | connection: 85 | $ref: parameters/_index.yaml#/parameters/connection 86 | feature: 87 | $ref: parameters/_index.yaml#/parameters/feature 88 | macSecKey: 89 | $ref: parameters/_index.yaml#/parameters/macSecKey 90 | issue: 91 | $ref: parameters/_index.yaml#/parameters/issue 92 | alt: 93 | $ref: parameters/_index.yaml#/parameters/alt 94 | callback: 95 | $ref: parameters/_index.yaml#/parameters/callback 96 | prettyPrint: 97 | $ref: parameters/_index.yaml#/parameters/prettyPrint 98 | _.xgafv: 99 | $ref: parameters/_index.yaml#/parameters/_.xgafv 100 | 101 | -------------------------------------------------------------------------------- /connection-coordinator/paths/features.yaml: -------------------------------------------------------------------------------- 1 | AllFeatures: 2 | get: 3 | description: List all features associated with a given connection. 4 | operationId: ListFeatures 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - $ref: "../parameters/_index.yaml#/parameters/environment" 8 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 9 | - $ref: "../parameters/_index.yaml#/parameters/connection" 10 | - description: |- 11 | The maximum number of features to return. The service may return fewer 12 | than this value. 13 | explode: true 14 | in: query 15 | name: pageSize 16 | required: false 17 | schema: 18 | format: int32 19 | type: integer 20 | style: form 21 | - description: |- 22 | A page token, received from a previous `ListFeatures` call. 23 | Provide this to retrieve the subsequent page. 24 | 25 | When paginating, all other parameters provided to `ListFeatures` must 26 | match the call that provided the page token. 27 | explode: true 28 | in: query 29 | name: pageToken 30 | required: false 31 | schema: 32 | type: string 33 | style: form 34 | responses: 35 | default: 36 | content: 37 | application/json: 38 | schema: 39 | $ref: "../schemas/feature.yaml#/ListFeaturesResponse" 40 | description: Successful operation 41 | security: [] 42 | tags: 43 | - Features 44 | post: 45 | description: |- 46 | Create a new feature associated with a connection. 47 | 48 | Multiple feature creation requests for the same resource may be sent by a 49 | remote provider simultaneously. The server provider must ensure that any 50 | resource reservations are performed sequentially across those requests to 51 | prevent race conditions. 52 | 53 | Typical feature creation flow: 54 | 55 | 1. Create server connection. 56 | 2. Request feature guidance for connection. 57 | 3. Select desired configuration parameters from guidance and create local 58 | feature. 59 | 4. Create server feature. 60 | 5. Await finalization. 61 | 62 | If *any* errors occur in the described flow, the remote provider is 63 | responsible for reconciling the server's state to determine if an existing 64 | request is in flight, retrying the provisioning flow with new parameters, 65 | or cleaning up resources and rejecting the customer's provisioning request. 66 | 67 | Errors: 68 | 409: CONFLICT. Returned when a server detect concurrent updates to the 69 | resource. 70 | operationId: CreateFeature 71 | parameters: 72 | - $ref: "../parameters/_index.yaml#/parameters/provider" 73 | - $ref: "../parameters/_index.yaml#/parameters/environment" 74 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 75 | - $ref: "../parameters/_index.yaml#/parameters/connection" 76 | - description: |- 77 | Required. The ID to use for the feature, which will become the final component of 78 | the feature's resource name. 79 | explode: true 80 | in: query 81 | name: featureId 82 | required: true 83 | schema: 84 | type: string 85 | style: form 86 | requestBody: 87 | content: 88 | application/json: 89 | schema: 90 | $ref: "../schemas/feature.yaml#/Feature" 91 | description: Required. The feature to create. 92 | responses: 93 | default: 94 | content: 95 | application/json: 96 | schema: 97 | $ref: "../schemas/feature.yaml#/Feature" 98 | description: Successful operation 99 | security: [] 100 | tags: 101 | - Features 102 | OneFeature: 103 | delete: 104 | description: Delete a specific feature. 105 | operationId: DeleteFeature 106 | parameters: 107 | - $ref: "../parameters/_index.yaml#/parameters/provider" 108 | - $ref: "../parameters/_index.yaml#/parameters/environment" 109 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 110 | - $ref: "../parameters/_index.yaml#/parameters/connection" 111 | - $ref: "../parameters/_index.yaml#/parameters/feature" 112 | responses: 113 | default: 114 | content: 115 | application/json: 116 | schema: 117 | $ref: "../schemas/common.yaml#/Empty" 118 | description: Successful operation 119 | security: [] 120 | tags: 121 | - Features 122 | get: 123 | description: Get details about a specific feature. 124 | operationId: GetFeature 125 | parameters: 126 | - $ref: "../parameters/_index.yaml#/parameters/provider" 127 | - $ref: "../parameters/_index.yaml#/parameters/environment" 128 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 129 | - $ref: "../parameters/_index.yaml#/parameters/connection" 130 | - $ref: "../parameters/_index.yaml#/parameters/feature" 131 | responses: 132 | default: 133 | content: 134 | application/json: 135 | schema: 136 | $ref: "../schemas/feature.yaml#/Feature" 137 | description: Successful operation 138 | security: [] 139 | tags: 140 | - Features 141 | -------------------------------------------------------------------------------- /connection-coordinator/paths/issues.yaml: -------------------------------------------------------------------------------- 1 | AllIssues: 2 | get: 3 | description: Lists Issues in a given project and location. 4 | operationId: ListIssues 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - description: 'Optional. The maximum number of issues to return. The service 8 | may return fewer than 9 | 10 | this value. If unspecified, at most 50 issues will be returned. The maximum 11 | 12 | value is 1000; values above 1000 will be coerced to 1000.' 13 | in: query 14 | name: pageSize 15 | schema: 16 | format: int32 17 | type: integer 18 | - description: 'Optional. A page token, received from a previous `ListIssues` 19 | call. 20 | 21 | Provide this to retrieve the subsequent page.' 22 | in: query 23 | name: pageToken 24 | schema: 25 | type: string 26 | responses: 27 | default: 28 | content: 29 | application/json: 30 | schema: 31 | $ref: "../schemas/issues.yaml#/ListIssuesResponse" 32 | description: Successful operation 33 | security: [] 34 | tags: 35 | - Issues 36 | post: 37 | description: Creates a new Issue in a given project and location. 38 | operationId: CreateIssue 39 | parameters: 40 | - $ref: "../parameters/_index.yaml#/parameters/provider" 41 | - description: 'Required. The ID to use for the issue, which will become the 42 | final component of the issue''s resource name.' 43 | in: query 44 | name: issueId 45 | required: true 46 | schema: 47 | type: string 48 | requestBody: 49 | content: 50 | application/json: 51 | schema: 52 | $ref: '../schemas/issues.yaml#/Issue' 53 | description: Required. The resource being created 54 | responses: 55 | default: 56 | content: 57 | application/json: 58 | schema: 59 | $ref: '../schemas/issues.yaml#/Issue' 60 | description: Successful operation 61 | security: [] 62 | tags: 63 | - Issues 64 | OneIssue: 65 | get: 66 | description: Gets details of a single Issue. 67 | operationId: GetIssue 68 | parameters: 69 | - $ref: "../parameters/_index.yaml#/parameters/provider" 70 | - $ref: "../parameters/_index.yaml#/parameters/issue" 71 | responses: 72 | default: 73 | content: 74 | application/json: 75 | schema: 76 | $ref: '../schemas/issues.yaml#/Issue' 77 | description: Successful operation 78 | security: [] 79 | tags: 80 | - Issues 81 | CloseIssue: 82 | post: 83 | description: Closes an Issue. 84 | operationId: CloseIssue 85 | parameters: 86 | - $ref: "../parameters/_index.yaml#/parameters/provider" 87 | - $ref: "../parameters/_index.yaml#/parameters/issue" 88 | requestBody: 89 | content: 90 | application/json: 91 | schema: 92 | $ref: '../schemas/issues.yaml#/CloseIssueRequest' 93 | description: The request body. 94 | responses: 95 | default: 96 | content: 97 | application/json: 98 | schema: 99 | $ref: '../schemas/issues.yaml#/Issue' 100 | description: Successful operation 101 | security: [] 102 | tags: 103 | - Issues 104 | AddComment: 105 | post: 106 | description: Adds a comment to a Issue. 107 | operationId: AddComment 108 | parameters: 109 | - $ref: "../parameters/_index.yaml#/parameters/provider" 110 | - $ref: "../parameters/_index.yaml#/parameters/issue" 111 | requestBody: 112 | content: 113 | application/json: 114 | schema: 115 | $ref: '../schemas/issues.yaml#/AddCommentRequest' 116 | description: The request body. 117 | responses: 118 | default: 119 | content: 120 | application/json: 121 | schema: 122 | $ref: '../schemas/issues.yaml#/AddCommentResponse' 123 | description: Successful operation 124 | security: [] 125 | tags: 126 | - Issues 127 | ListComments: 128 | get: 129 | description: Lists comments for a Issue. 130 | operationId: ListComments 131 | parameters: 132 | - $ref: "../parameters/_index.yaml#/parameters/provider" 133 | - $ref: "../parameters/_index.yaml#/parameters/issue" 134 | - description: 'Optional. The maximum number of comments to return. The service 135 | may return fewer than 136 | 137 | this value. If unspecified, at most 50 comments will be returned. The 138 | 139 | maximum value is 1000; values above 1000 will be coerced to 1000.' 140 | in: query 141 | name: pageSize 142 | schema: 143 | format: int32 144 | type: integer 145 | - description: 'Optional. A page token, received from a previous `ListComments` 146 | call. 147 | 148 | Provide this to retrieve the subsequent page.' 149 | in: query 150 | name: pageToken 151 | schema: 152 | type: string 153 | responses: 154 | default: 155 | content: 156 | application/json: 157 | schema: 158 | $ref: '../schemas/issues.yaml#/ListCommentsResponse' 159 | description: Successful operation 160 | security: [] 161 | tags: 162 | - Issues 163 | -------------------------------------------------------------------------------- /connection-coordinator/schemas/feature.yaml: -------------------------------------------------------------------------------- 1 | Feature: 2 | description: |- 3 | Feature resources describe all configuration per-channel that is required to 4 | enable a feature for a specified connection. 5 | example: 6 | name: name 7 | channel: channel 8 | featureConfig: "" 9 | provisioningState: "" 10 | properties: 11 | name: 12 | description: Identifier. A unique identifier for the feature resource. 13 | type: string 14 | channel: 15 | description: |- 16 | Required. The URI of the channel this feature is associated with. 17 | 18 | Each feature is only associated with a single channel and the channel must 19 | exist. Each connection resource will have a child feature for each channel 20 | that is a child of the parent interconnect resource. For example a 21 | connection that is a child of an interconnect with 4 channels will have 4 22 | child features, each associated with a different channel. 23 | type: string 24 | featureConfig: 25 | allOf: 26 | - $ref: "#/FeatureConfig" 27 | description: All configuration associated with the feature. 28 | provisioningState: 29 | allOf: 30 | - $ref: "common.yaml#/ProvisioningState" 31 | description: Output only. The provisioning state of the feature. 32 | readOnly: true 33 | type: object 34 | 35 | FeatureType: 36 | description: FEATURE_TYPE_L3_BASE - Primary feature used to connect Layer 3 37 | traffic. 38 | enum: 39 | - FEATURE_TYPE_L3_BASE 40 | type: string 41 | FeatureConfig: 42 | description: Feature specific configuration associated with a Feature resource. 43 | properties: 44 | featureType: 45 | allOf: 46 | - $ref: "#/FeatureType" 47 | description: The feature type this configuration contains. 48 | l3BaseConfig: 49 | allOf: 50 | - $ref: "#/L3BaseConfig" 51 | description: All configuration associated with the FEATURE_TYPE_L3_BASE 52 | type: object 53 | L3BaseConfig: 54 | description: All FEATURE_TYPE_L3_BASE configuration. 55 | properties: 56 | ipv4Subnet: 57 | description: |- 58 | Required. IPv4 subnet used to establish L3 connectivity for the customer 59 | 60 | Note: The IP address must have the subnet mask applied to it. 61 | type: string 62 | ipv4SubnetPrefixLength: 63 | description: Required. IPv4 subnet prefix length. 64 | format: int32 65 | type: integer 66 | ipv6Subnet: 67 | description: |- 68 | Optional. IPv6 subnet used to establish L3 connectivity for the customer 69 | 70 | Note: The IP address must have the subnet mask applied to it. 71 | type: string 72 | ipv6SubnetPrefixLength: 73 | description: Optional. IPv6 subnet prefix length. 74 | format: int32 75 | type: integer 76 | mtuBytes: 77 | description: |- 78 | Required. MTU for VLAN attachments. 79 | 80 | Special note: This represents the MTU at the connection points 81 | between providers, there may be further MTU limitations within provider 82 | networks. 83 | format: int32 84 | type: integer 85 | vlanId: 86 | description: |- 87 | Required. VLAN ID used by the connection. 88 | 89 | VLAN 1024 and lower are reserved and cannot have features associated with 90 | them. Otherwise, a provider may select from any available VLANs. 91 | format: int32 92 | type: integer 93 | providerBgpConfigs: 94 | description: |- 95 | Required. A mapping of provider ID to all BGP session attributes the provider 96 | should use. 97 | items: 98 | $ref: "#/ProviderBgpConfig" 99 | type: array 100 | md5BgpPassword: 101 | description: Shared MD5 password for BGP sessions. 102 | type: string 103 | type: object 104 | ProviderBgpConfig: 105 | description: |- 106 | All parameters needed for a provider to configure a BGP session 107 | associated with a channel. 108 | properties: 109 | provider: 110 | description: |- 111 | Required. The resource name of the provider that this BGP configuration is 112 | associated with. 113 | type: string 114 | asn: 115 | description: Required. The ASN associated with the provider. 116 | format: int32 117 | type: integer 118 | hostIpv4: 119 | description: Required. IPv4 address hosting BGP session for provider. 120 | type: string 121 | hostIpv6: 122 | description: Optional. IPv6 address hosting BGP session for provider. 123 | type: string 124 | type: object 125 | 126 | ListFeaturesResponse: 127 | description: Response for obtaining multiple feature resources. 128 | example: 129 | features: 130 | - name: name 131 | channel: channel 132 | featureConfig: "" 133 | provisioningState: "" 134 | - name: name 135 | channel: channel 136 | featureConfig: "" 137 | provisioningState: "" 138 | nextPageToken: nextPageToken 139 | properties: 140 | features: 141 | description: The features from the specified provider. 142 | items: 143 | $ref: "#/Feature" 144 | type: array 145 | nextPageToken: 146 | description: |- 147 | A token, which can be sent as `page_token` to retrieve the next page. 148 | If this field is omitted, there are no subsequent pages. 149 | type: string 150 | type: object 151 | 152 | -------------------------------------------------------------------------------- /governance/SECURITY_AND_OPERATIONAL_EXCELLENCE.md: -------------------------------------------------------------------------------- 1 | # Security and Operational Excellence Policy 2 | 3 | This policy establishes the security and operational excellence requirements for the Connection Coordinator API specification, which enables cross-provider direct connections between cloud service providers. As an openly licensed specification under Apache 2.0, we encourage broad adoption and contribution from the cloud provider community. 4 | 5 | To maintain the integrity, security, and reliability of implementations, we have established this policy to define minimum standards that all specification changes must adhere to. This ensures that while the specification remains open and adaptable, critical security and operational capabilities are preserved across all implementations. 6 | 7 | The primary goals of this policy are to: 8 | 1. Protect customer data traversing cross-provider connections 9 | 2. Ensure consistent security practices across all implementing cloud providers 10 | 3. Maintain operational reliability for mission-critical workloads 11 | 4. Provide clear guidance for contributors proposing specification changes 12 | 13 | All proposed changes to the specification must comply with these requirements. The project Maintaining Organizations will evaluate contributions against these standards to preserve the security-first design and operational excellence principles that are foundational to this initiative. Per the Governance Framework, this policy will be reviewed annually to ensure that these tenets are still necessary to achieve the project’s performance and security objectives. 14 | 15 | ## Core Security Tenets 16 | 17 | ### Mandatory Encryption 18 | - No changes that make encryption optional or weaken encryption standards will be accepted. 19 | - At least TLS 1.3 must be used for all API communications between providers. 20 | - Connection features that support encryption (like MACsec) must remain mandatory where specified. 21 | 22 | ### Authentication and Authorization 23 | - All API endpoints must implement authentication mechanisms that follow encryption and security best practices, such as AWS’ Well-architected recommendations and in particular the Security and Operational Excellence Pillars https://aws.amazon.com/architecture/well-architected/ and Google’s Well-Architected Framework: Security, privacy, and compliance pillar https://docs.cloud.google.com/architecture/framework/security. 24 | - The specification must maintain clear provider identity verification. 25 | - The security sections in API paths must not be emptied or weakened. 26 | - Activation key validation must remain a required step in connection establishment. 27 | - Confused Deputy Resolution is required and any changes suggesting its removal from any API will not be accepted. 28 | 29 | ### Connection Integrity 30 | - The activation key mechanism must be preserved to ensure proper connection authorization. 31 | - Key material must remain properly secured and obfuscated as specified. 32 | - No changes that bypass activation key validation will be accepted, unless replaced with an objectively stronger mechanism. 33 | 34 | ### Secure Channel Management 35 | - The MACsec manager provider role must be maintained to ensure proper encryption key management. 36 | - Channel security features must not be removed to simplify implementation. 37 | 38 | ## Operational Excellence Tenets 39 | 40 | ### Service Reliability 41 | - Maintenance event notifications must remain part of the specification. 42 | - Connection status monitoring capabilities must be preserved. 43 | - The specification must maintain support for administrative status controls. 44 | 45 | ### Resource Management 46 | - Bandwidth allocation mechanisms must be preserved. 47 | - No APIs for bandwidth reservations will be accepted. 48 | - Connection resource cleanup requirements (e.g., 7-day deletion policy) must be maintained. 49 | - Adherence to Activation Key lifetimes is required. 50 | - Capacity planning features must not be removed from the specification. 51 | 52 | ### Fault Isolation 53 | - Channel diversity requirements must be maintained. 54 | - The obfuscated device ID mechanism must be preserved to ensure proper diversity tracking. 55 | - No changes that would compromise redundancy capabilities will be accepted. 56 | 57 | ## Implementation Requirements 58 | 59 | ### Specification Compliance 60 | - All implementations must support the full API specification. 61 | - Any additional API features are considered optional, but if implemented, must be implemented in full. 62 | - Implementations must maintain all required fields marked as such in the specification. 63 | 64 | ### Feature Compatibility 65 | - All implementations must support the defined feature types. 66 | - The L3 base feature configuration must be fully implemented. 67 | - No changes that would break interoperability between providers will be accepted. 68 | 69 | ### Protocol Standards 70 | - BGP session security features must be preserved. 71 | - MTU and VLAN configuration capabilities must be maintained. 72 | - IP subnet management features must be fully implemented. 73 | 74 | ## Change Management Policy 75 | 76 | ### Security Impact Assessment 77 | - All proposed changes must include a security impact assessment. 78 | - Changes that reduce security capabilities will be rejected. 79 | - Security considerations must take precedence over implementation simplicity. 80 | 81 | ### Backward Compatibility 82 | - Changes must maintain backward compatibility where possible. 83 | - Breaking changes must provide clear migration paths. 84 | - Version management must follow semantic versioning principles. 85 | 86 | ### Documentation Requirements 87 | - All changes must include appropriate documentation updates. 88 | - Security implications must be clearly documented. 89 | - Implementation guidance must be provided for security-critical features. 90 | 91 | -------------------------------------------------------------------------------- /connection-coordinator/schemas/channel.yaml: -------------------------------------------------------------------------------- 1 | Channel: 2 | description: |- 3 | Channels describe individual physical connections that connect a remote 4 | provider's router to a server provider's router. 5 | 6 | The following fields are pre-exchanged between providers when 7 | provisioning capacity: 8 | 9 | 1. name 10 | 11 | 2. macsec_manager_provider_id 12 | 13 | 3. cross_connect_manager_provider_id 14 | 15 | All other fields within the channel are populated by the server provider. 16 | example: 17 | demarc: demarc 18 | crossConnectManagerProvider: crossConnectManagerProvider 19 | channelMemberSizeGbps: 6 20 | name: name 21 | adminState: "" 22 | macsecManagerProvider: macsecManagerProvider 23 | aggregateChannelSizeGbps: 0 24 | obfuscatedDeviceId: obfuscatedDeviceId 25 | properties: 26 | name: 27 | description: Identifier. Unique identifier for the Channel resource. 28 | type: string 29 | macsecManagerProvider: 30 | description: |- 31 | Output only. The URI of the provider responsible for managing MacSec key rotations. 32 | 33 | This field must prevent the non-manager provider from calling Macsec 34 | APIs. 35 | readOnly: true 36 | type: string 37 | crossConnectManagerProvider: 38 | description: |- 39 | Output only. The URI of the provider responsible for managing physical crossconnects. This 40 | includes cross connect costs and any troubleshooting requests to the vendor 41 | providing the cross connect. 42 | readOnly: true 43 | type: string 44 | aggregateChannelSizeGbps: 45 | description: Output only. Aggregate channel size in gigabits per second. 46 | format: int32 47 | readOnly: true 48 | type: integer 49 | channelMemberSizeGbps: 50 | description: Output only. Individual channel member size in gigabits per 51 | second. 52 | format: int32 53 | readOnly: true 54 | type: integer 55 | obfuscatedDeviceId: 56 | description: |- 57 | Output only. An obfuscated device ID associated with the network device hosting the 58 | channel. This field allows providers to check that channel diversity 59 | requirements are met within a parent interconnect resource. 60 | readOnly: true 61 | type: string 62 | demarc: 63 | description: |- 64 | A demarcation identifier that uniquely identifies where the cross connect 65 | is connected. This identifier is typically provided by the colocation 66 | facility and can be found in letters of authorization when turning up 67 | capacity. 68 | type: string 69 | adminState: 70 | allOf: 71 | - $ref: common.yaml#/AdminState 72 | description: |- 73 | Output only. The administrative status of the channel. This field is used by a provider 74 | to signal a channel has been intentionally disabled. 75 | readOnly: true 76 | type: object 77 | 78 | ListChannelsResponse: 79 | description: Response for obtaining multiple channel resources. 80 | example: 81 | channels: 82 | - demarc: demarc 83 | crossConnectManagerProvider: crossConnectManagerProvider 84 | channelMemberSizeGbps: 6 85 | name: name 86 | adminState: "" 87 | macsecManagerProvider: macsecManagerProvider 88 | aggregateChannelSizeGbps: 0 89 | obfuscatedDeviceId: obfuscatedDeviceId 90 | - demarc: demarc 91 | crossConnectManagerProvider: crossConnectManagerProvider 92 | channelMemberSizeGbps: 6 93 | name: name 94 | adminState: "" 95 | macsecManagerProvider: macsecManagerProvider 96 | aggregateChannelSizeGbps: 0 97 | obfuscatedDeviceId: obfuscatedDeviceId 98 | nextPageToken: nextPageToken 99 | properties: 100 | channels: 101 | description: The channels from the specified provider. 102 | items: 103 | $ref: "#/Channel" 104 | type: array 105 | nextPageToken: 106 | description: |- 107 | A token, which can be sent as `page_token` to retrieve the next page. 108 | If this field is omitted, there are no subsequent pages. 109 | type: string 110 | type: object 111 | 112 | NotifyMaintenanceRequest: 113 | description: |- 114 | A notification from a remote provider that a maintenance has been updated on 115 | a channel. 116 | example: 117 | events: 118 | - maintenanceId: maintenanceId 119 | startTime: 2000-01-23T04:56:07.000+00:00 120 | endTime: 2000-01-23T04:56:07.000+00:00 121 | - maintenanceId: maintenanceId 122 | startTime: 2000-01-23T04:56:07.000+00:00 123 | endTime: 2000-01-23T04:56:07.000+00:00 124 | properties: 125 | events: 126 | description: |- 127 | All maintenance events associated with the channel. At the time of sending 128 | the notification. 129 | items: 130 | $ref: "#/MaintenanceEvent" 131 | type: array 132 | type: object 133 | 134 | MaintenanceEvent: 135 | description: A maintenance event scheduled or in progress associated with a 136 | channel. 137 | example: 138 | maintenanceId: maintenanceId 139 | startTime: 2000-01-23T04:56:07.000+00:00 140 | endTime: 2000-01-23T04:56:07.000+00:00 141 | properties: 142 | startTime: 143 | description: The timestamp when a maintenance will start or started in the 144 | past. 145 | format: date-time 146 | type: string 147 | endTime: 148 | description: The timestamp when a maintenance will end. 149 | format: date-time 150 | type: string 151 | maintenanceId: 152 | description: |- 153 | An opaque maintenance identifier that can be used when communicating with 154 | a provider to uniquely identify the maintenance event. 155 | type: string 156 | type: object 157 | 158 | GetMaintenanceEventsResponse: 159 | description: Response for getting maintenance events for a channel. 160 | example: 161 | events: 162 | - maintenanceId: maintenanceId 163 | startTime: 2000-01-23T04:56:07.000+00:00 164 | endTime: 2000-01-23T04:56:07.000+00:00 165 | - maintenanceId: maintenanceId 166 | startTime: 2000-01-23T04:56:07.000+00:00 167 | endTime: 2000-01-23T04:56:07.000+00:00 168 | properties: 169 | events: 170 | description: The maintenance events for the specified channel. 171 | items: 172 | $ref: "#/MaintenanceEvent" 173 | type: array 174 | type: object 175 | -------------------------------------------------------------------------------- /connection-coordinator/schemas/environment.yaml: -------------------------------------------------------------------------------- 1 | Environment: 2 | description: |- 3 | Environments define high level connection points between two providers. 4 | 5 | Environment resources support the following 6 | 1. Conveying to end customers where and how two providers can be connected. 7 | 2. Display information for describing these environments. 8 | 9 | Providers exchange environment information when establishing connectivity and 10 | this resource is provided for troubleshooting and validation purposes. 11 | Providers generally have a local copy of this information and do not need to 12 | request it when servicing requests. 13 | example: 14 | providerSites: 15 | - site: site 16 | providerId: providerId 17 | displayName: displayName 18 | - site: site 19 | providerId: providerId 20 | displayName: displayName 21 | apiUri: apiUri 22 | supportedFeatures: 23 | - FEATURE_TYPE_L3_BASE 24 | - FEATURE_TYPE_L3_BASE 25 | name: name 26 | environmentVisibility: "" 27 | supportedConnectionSizeMbps: 28 | - 0 29 | - 0 30 | properties: 31 | name: 32 | description: Identifier. Unique identifier for an Environment resource. 33 | type: string 34 | providerSites: 35 | description: |- 36 | Output only. A unique mapping between a provider and a site code. This field should 37 | never contain more than 2 entries. One entry should be a mapping 38 | between the server's provider ID and a site identifier, the other entry 39 | should be the parent provider ID and a site identifier. 40 | 41 | Example: [ 42 | {"providerId": "provider1", "site": "us-east4"}, 43 | {"providerId": "provider2", "site": "us-east1"}, 44 | ] 45 | items: 46 | $ref: "#/ProviderSites" 47 | readOnly: true 48 | type: array 49 | apiUri: 50 | description: |- 51 | API endpoint for communicating with the parent provider about this 52 | environment resource and all child resources. 53 | 54 | Example: 55 | remoteprovider.com/projects/123/locations/us-east4/ 56 | type: string 57 | supportedConnectionSizeMbps: 58 | description: |- 59 | Output only. A list of Mbps connection sizes supported by all interconnects in the 60 | environment. 61 | items: 62 | format: int32 63 | type: integer 64 | readOnly: true 65 | type: array 66 | supportedFeatures: 67 | description: Output only. A list of features supported by all interconnects 68 | in the environment. 69 | items: 70 | $ref: "feature.yaml#/FeatureType" 71 | readOnly: true 72 | type: array 73 | environmentVisibility: 74 | allOf: 75 | - $ref: "#/EnvironmentVisibility" 76 | description: |- 77 | Output only. Controls the visibility of this environment in the provider's customer 78 | facing APIs. 79 | readOnly: true 80 | type: object 81 | 82 | ProviderSites: 83 | description: A mapping of a provider id to their API and display names for sites. 84 | example: 85 | site: site 86 | providerId: providerId 87 | displayName: displayName 88 | properties: 89 | providerId: 90 | description: Which provider this site data is associated with. 91 | type: string 92 | site: 93 | description: A provider specific site name (e.g. us-east4). 94 | type: string 95 | displayName: 96 | description: A display name for the site for use in customer facing UI. 97 | type: string 98 | type: object 99 | 100 | EnvironmentVisibility: 101 | description: |- 102 | Enum that describes the visibility of an environment. 103 | ENVIRONMENT_VISIBILITY_PRIVATE - A private environment has limited visibility (as jointly defined by 104 | providers) to an individual or small number of customers. 105 | ENVIRONMENT_VISIBILITY_PUBLIC - A public environment is visible to all provider customers with little to no 106 | restriction. 107 | enum: 108 | - ENVIRONMENT_VISIBILITY_PRIVATE 109 | - ENVIRONMENT_VISIBILITY_PUBLIC 110 | type: string 111 | 112 | ListEnvironmentsResponse: 113 | description: Response for obtaining multiple environment resources. 114 | example: 115 | environments: 116 | - providerSites: 117 | - site: site 118 | providerId: providerId 119 | displayName: displayName 120 | - site: site 121 | providerId: providerId 122 | displayName: displayName 123 | apiUri: apiUri 124 | supportedFeatures: 125 | - FEATURE_TYPE_L3_BASE 126 | - FEATURE_TYPE_L3_BASE 127 | name: name 128 | environmentVisibility: "" 129 | supportedConnectionSizeMbps: 130 | - 0 131 | - 0 132 | - providerSites: 133 | - site: site 134 | providerId: providerId 135 | displayName: displayName 136 | - site: site 137 | providerId: providerId 138 | displayName: displayName 139 | apiUri: apiUri 140 | supportedFeatures: 141 | - FEATURE_TYPE_L3_BASE 142 | - FEATURE_TYPE_L3_BASE 143 | name: name 144 | environmentVisibility: "" 145 | supportedConnectionSizeMbps: 146 | - 0 147 | - 0 148 | nextPageToken: nextPageToken 149 | properties: 150 | environments: 151 | description: The environments from the specified provider. 152 | items: 153 | $ref: "#/Environment" 154 | type: array 155 | nextPageToken: 156 | description: |- 157 | A token, which can be sent as `page_token` to retrieve the next page. 158 | If this field is omitted, there are no subsequent pages. 159 | type: string 160 | type: object 161 | 162 | ConfirmActivationKeyRequest: 163 | description: |- 164 | Request to confirm the validity of a activation key provided by a remote 165 | provider. 166 | example: 167 | key: "" 168 | properties: 169 | key: 170 | allOf: 171 | - $ref: "#/ActivationKey" 172 | description: Activation key to be confirmed. 173 | type: object 174 | 175 | ActivationKey: 176 | description: |- 177 | Activation Keys contain all information needed by a provider to validate a 178 | activation proposal between two provider. 179 | 180 | The activation key should be base64 encoded whenever it is exchanged between 181 | providers. This helps prevent accidental corruption of the key when 182 | transferring it between clouds. 183 | properties: 184 | version: 185 | description: |- 186 | Required. Version of the ActivationKey itself. The version should 187 | match the API version on the creating service. 188 | format: int32 189 | type: integer 190 | destinationEnvironmentUri: 191 | description: |- 192 | Required. The destination environment URI this activation key is 193 | intended for use at. 194 | type: string 195 | sharedConnectionUuid: 196 | description: Required. The UUID assigned to this connection to be used by 197 | both services. 198 | type: string 199 | connectionSizeMbps: 200 | description: Required. Size of the connection to be provisioned in mbps. 201 | format: int32 202 | type: integer 203 | destinationAccountId: 204 | description: |- 205 | Required. User supplied account id/number on the destination CSP. 206 | Receiving service MUST verify that the activation key was provided from an authorized user of this account. 207 | type: string 208 | required: 209 | - connectionSizeMbps 210 | - destinationAccountId 211 | - destinationEnvironmentUri 212 | - sharedConnectionUuid 213 | - version 214 | type: object 215 | 216 | ConfirmActivationKeyResponse: 217 | description: |- 218 | Response from a provider about the validity of the key and any additional 219 | metadata that is needed for turn up. 220 | example: 221 | keyValid: true 222 | properties: 223 | keyValid: 224 | description: Indicates if the remote CSP believes this key is valid. 225 | type: boolean 226 | type: object -------------------------------------------------------------------------------- /governance/GOVERNANCE_MODEL.md: -------------------------------------------------------------------------------- 1 | # Governance Model - Project Governance Framework 2 | 3 | This open source project is managed by a Steering Committee composed of representatives from Maintaining Organizations. Maintaining Organizations are defined as the Founding Members and any additional members added by way of the processes described herein, listed in the MAINTAINING_ORGS.md file in the project repository. 4 | 5 | ## Member Categories 6 | 7 | The project recognizes three categories of members: 8 | 1. **Founding Members**: Amazon Web Services and Google are designated as Founding Members of this project 9 | 2. **Maintaining Organizations**: Organizations who contribute to and maintain the specification, with full commit access to the project repositories 10 | 3. **Implementers**: Organizations that are actively implementing the specification in accordance with the Security and Operational Excellence Policy in production cloud environments, but have not yet become a Maintaining Organization 11 | 12 | ## Addition and Removal of Members 13 | ### Founding Members 14 | 15 | The Founding Members are the initial Maintaining Organizations. Removal of a Founding Member requires consent of that founding member. Aside from removal, Founding Members are treated the same as any other member and have no special voting or governance privileges beyond removal protection and those of its members who serve on the Steering Committee. 16 | 17 | ### Maintaining Organizations 18 | 19 | To qualify as a Maintaining Organization, an organization must demonstrate: 20 | 1. Commitment to the Security and Operational Excellence Policy, demonstrated by 2 and 3; 21 | 2. Proven ability to implement and maintain the specification in a production environment for at least a year; and 22 | 3. History of constructive, security-compliant contribution to the project. 23 | The Steering Committee will evaluate Maintaining Organization candidates to determine whether they have met the above criteria, with particular emphasis on their demonstrated commitment to the project's security and operational standards. Maintaining Organizations may be added or removed by no less than 3/4 affirmative vote of the Steering Committee, however a Maintaining Organization is free to remove itself at any time by written notice to the Steering Committee. 24 | 25 | ### Implementers 26 | 27 | Implementers, listed in the IMPLEMENTERS.md file in the repository, may be added or removed by no less than 3/4 affirmative vote of the Steering Committee, based on an assessment of whether the production implementation aligns with all requirements of the specification and the Security and Operational Excellence Policy. 28 | 29 | ### Removal Criteria 30 | 31 | A Maintaining Organization or Implementer may be considered for removal by the Steering Committee if any of the following conditions are met: 32 | 33 | 1. Lack of Participation: The member has been inactive or non-responsive in project activities for a period of six months or more, including failure to participate in votes, respond to communications, or contribute to the project's development. 34 | 2. Policy Non-Compliance: The member has demonstrated a pattern of non-compliance with the Security and Operational Excellence Policy. 35 | 3. Disruptive Conduct: The member has engaged in conduct that significantly disrupts the project's operations or damages its reputation, including violations of the project Code of Conduct https://aws.github.io/code-of-conduct. 36 | Any Maintaining Organization may propose another member for removal by submitting a written request to the Steering Committee Chair, who will then initiate the removal process. The member proposed for removal will be given reasonable notice and an opportunity to address the concerns before a vote is taken. 37 | 38 | Removal requires a 3/4 affirmative vote of the Steering Committee, with the member proposed for removal recusing themselves from the vote if they are a Maintaining Organization, except for Founding Members who must consent to their removal. Any member may also choose to remove themselves. 39 | 40 | ## Representation 41 | 42 | The Steering Committee will be responsible for oversight of all technical, project, approval, and policy matters for the project. Each Maintaining Organization will designate one Steering Committee member, listed in the STEERING_COMMITTEE.md file in the repository. This representative will cast the Maintaining Organization's single vote in formal voting matters. 43 | 44 | The Steering Committee will appoint a Chair responsible for organizing the Steering Committee’s activity. If the Steering Committee Chair is removed from the Committee (or the Chair steps down from that role), it is the responsibility of the Steering Committee to appoint a new Chair. 45 | 46 | Each Maintaining Organization may designate up to 3 individuals with full commit access to the project repositories, listed in the MAINTAINERS.md file in the repository, and can provide as many experts as needed for the Technical Advisory Board (TAB). 47 | 48 | Maintaining Organizations have full voting rights through participation in the Steering Committee, and Implementers have voting rights on changes that impose significant implementation burdens, with each Implementer getting a single vote. 49 | 50 | ## Voting 51 | 52 | The Steering Committee will strive for all decisions to be made by consensus. While explicit agreement of the entire Steering Committee is preferred, it is not required for consensus. Rather, the Steering Committee will determine consensus based on their good faith consideration of a number of factors, including the collective views of the Steering Committee members, the technical merits of the positions expressed, alignment with project goals, and the substantive nature of support and objections. 53 | 54 | If consensus cannot be reached, the Steering Committee will make the decision by a vote. The Steering Committee Chair will call a vote with reasonable notice to the Steering Committee, setting out a discussion period and a separate voting period. 55 | 56 | Voting will also be used for: 57 | - the addition or removal of Maintaining Organizations and Implementers; 58 | - adoption of resource-intensive changes; 59 | - changes to this Project Governance framework; and 60 | - changes to the Security and Operational Excellence Policy. 61 | Except as specifically noted elsewhere in this document, decisions by vote require a simple majority vote of all voting members. 62 | 63 | ### Resource-Intensive Changes 64 | 65 | For changes that would impose significant implementation burdens (substantial hardware changes, major architectural modifications, or significant engineering effort), the following special voting process applies: 66 | 1. Any Maintaining Organization may designate a proposed change as "resource-intensive" during the discussion period. 67 | 2. If designated as resource-intensive, the change requires a vote including the Steering Committee and a representative from each Implementer. 68 | To be approved, a resource-intensive change must receive a majority vote from the Maintaining Organizations and at least one vote from an Implementer, if there are Implementers. This ensures that no single party can unilaterally impose significant resource requirements on other implementers, while still allowing the specification to evolve. 69 | 70 | ### Security and Operational Excellence Policy Changes 71 | 72 | Changes to the Security and Operational Excellence Policy require a 3/4 affirmative vote of the Steering Committee, reflecting the critical importance of maintaining high security standards. 73 | 74 | ## Technical Advisory Board 75 | 76 | A Technical Advisory Board (TAB) consisting of technical experts from Maintaining Organizations will convene as needed to: 77 | 1. Evaluate the technical feasibility of proposed changes 78 | 2. Evaluate compliance of proposed changes with the Security and Operational Excellence Policy 79 | 3. Assess implementation burden of proposed changes, and provide recommendations to the Steering Committee on resource-intensive changes 80 | The TAB will operate in an advisory capacity and does not have direct voting rights beyond those of its members who serve on the Steering Committee. 81 | 82 | ## Transparency 83 | 84 | All Steering Committee and TAB meetings, decisions, and recommendations shall be documented and published in the project repository, subject to reasonable restrictions on confidentiality to maintain commercially sensitive information or information pertaining to the security of the project or the Maintaining Organizations. 85 | 86 | ## Annual Review 87 | 88 | The Steering Committee will conduct an annual review of all of the following: 89 | 1. This Project Governance 90 | 2. The Security and Operational Excellence Policy 91 | 3. Maintaining Organization composition and contributions 92 | 4. Implementer membership 93 | -------------------------------------------------------------------------------- /connection-coordinator/paths/connections.yaml: -------------------------------------------------------------------------------- 1 | AllConnections: 2 | get: 3 | description: List all connections associated with a given interconnect. 4 | operationId: ListConnections 5 | parameters: 6 | - $ref: "../parameters/_index.yaml#/parameters/provider" 7 | - $ref: "../parameters/_index.yaml#/parameters/environment" 8 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 9 | - description: |- 10 | The maximum number of connections to return. The service may return fewer 11 | than this value. 12 | explode: true 13 | in: query 14 | name: pageSize 15 | required: false 16 | schema: 17 | format: int32 18 | type: integer 19 | style: form 20 | - description: |- 21 | A page token, received from a previous `ListConnections` call. 22 | Provide this to retrieve the subsequent page. 23 | 24 | When paginating, all other parameters provided to `ListConnections` must 25 | match the call that provided the page token. 26 | explode: true 27 | in: query 28 | name: pageToken 29 | required: false 30 | schema: 31 | type: string 32 | style: form 33 | responses: 34 | default: 35 | content: 36 | application/json: 37 | schema: 38 | $ref: "../schemas/connection.yaml#/ListConnectionsResponse" 39 | description: Successful operation 40 | security: [] 41 | tags: 42 | - Connections 43 | post: 44 | description: |- 45 | Create a new connection associated with a given interconnect. 46 | 47 | When calling this API, remote providers must first create a connection 48 | resource locally. This ensures the remote provider can handle server 49 | failures (retries and cleanup). 50 | 51 | If connection creation fails, the provider should restart their call flow 52 | refreshing any environment and interconnect details used to create the 53 | request and retry. When retrying, client should use an exponential 54 | backoff strategy for up to 60 seconds. 55 | 56 | Errors: 57 | 409: CONFLICT. The resource is being created or has already been 58 | created. 59 | operationId: CreateConnection 60 | parameters: 61 | - $ref: "../parameters/_index.yaml#/parameters/provider" 62 | - $ref: "../parameters/_index.yaml#/parameters/environment" 63 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 64 | - description: |- 65 | Required. The ID to use for the connection, which will become the final component of 66 | the connection's resource name. 67 | explode: true 68 | in: query 69 | name: connectionId 70 | required: true 71 | schema: 72 | type: string 73 | style: form 74 | requestBody: 75 | content: 76 | application/json: 77 | schema: 78 | $ref: "../schemas/connection.yaml#/Connection" 79 | description: Required. The connection to create. 80 | responses: 81 | default: 82 | content: 83 | application/json: 84 | schema: 85 | $ref: "../schemas/connection.yaml#/Connection" 86 | description: Successful operation 87 | security: [] 88 | tags: 89 | - Connections 90 | OneConnection: 91 | delete: 92 | description: Delete a specific connection. 93 | operationId: DeleteConnection 94 | parameters: 95 | - $ref: "../parameters/_index.yaml#/parameters/provider" 96 | - $ref: "../parameters/_index.yaml#/parameters/environment" 97 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 98 | - $ref: "../parameters/_index.yaml#/parameters/connection" 99 | responses: 100 | default: 101 | content: 102 | application/json: 103 | schema: 104 | $ref: "../schemas/common.yaml#/Empty" 105 | description: Successful operation 106 | security: [] 107 | tags: 108 | - Connections 109 | get: 110 | description: Get details about a specific connection. 111 | operationId: GetConnection 112 | parameters: 113 | - $ref: "../parameters/_index.yaml#/parameters/provider" 114 | - $ref: "../parameters/_index.yaml#/parameters/environment" 115 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 116 | - $ref: "../parameters/_index.yaml#/parameters/connection" 117 | responses: 118 | default: 119 | content: 120 | application/json: 121 | schema: 122 | $ref: "../schemas/connection.yaml#/Connection" 123 | description: Successful operation 124 | security: [] 125 | tags: 126 | - Connections 127 | patch: 128 | description: |- 129 | Update a specific connection's attributes. 130 | 131 | When calling this API if the field being updated is synchronized between 132 | the providers, the remote provider should update their local connection 133 | state before requesting an update to the server provider resource. When 134 | requesting an update to a connection, all remote provider update requests 135 | must be rejected. 136 | 137 | Errors: 138 | 409: CONFLICT. Returned when a server detect concurrent updates to the 139 | resource. 140 | operationId: UpdateConnection 141 | parameters: 142 | - $ref: "../parameters/_index.yaml#/parameters/provider" 143 | - $ref: "../parameters/_index.yaml#/parameters/environment" 144 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 145 | - $ref: "../parameters/_index.yaml#/parameters/connection" 146 | - description: The list of fields to update. 147 | explode: true 148 | in: query 149 | name: updateMask 150 | required: false 151 | schema: 152 | format: fieldmask 153 | pattern: "^(\\s*[^,\\s.]+(\\s*[,.]\\s*[^,\\s.]+)*)?$" 154 | type: string 155 | style: form 156 | requestBody: 157 | content: 158 | application/json: 159 | schema: 160 | $ref: "../schemas/connection.yaml#/Connection" 161 | description: Required. The connection to update. 162 | responses: 163 | default: 164 | content: 165 | application/json: 166 | schema: 167 | $ref: "../schemas/connection.yaml#/Connection" 168 | description: Successful operation 169 | security: [] 170 | tags: 171 | - Connections 172 | GenerateFeatureGuidance: 173 | post: 174 | description: |- 175 | Requests the server to generate feature guidance for all channels associated 176 | with a given connection and return the results. 177 | operationId: GenerateFeatureGuidance 178 | parameters: 179 | - $ref: "../parameters/_index.yaml#/parameters/provider" 180 | - $ref: "../parameters/_index.yaml#/parameters/environment" 181 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 182 | - $ref: "../parameters/_index.yaml#/parameters/connection" 183 | requestBody: 184 | content: 185 | application/json: 186 | schema: 187 | $ref: "../schemas/connection.yaml#/GenerateFeatureGuidanceRequest" 188 | description: The request body. 189 | responses: 190 | default: 191 | content: 192 | application/json: 193 | schema: 194 | $ref: "../schemas/connection.yaml#/GenerateFeatureGuidanceResponse" 195 | description: Successful operation 196 | security: [] 197 | tags: 198 | - Connections 199 | NotifyConnectionStatus: 200 | post: 201 | description: |- 202 | Notify a remote provider that the provisioning status of a connection has 203 | changed. 204 | 205 | A provider will typically send a remote provider two updates: 206 | 1) A notification when a newly created channel has transitioned from 207 | PENDING to FINALIZED 208 | 2) A notification when an existing channel transitions from FINALIZED 209 | to PENDING. This happens when features change and need finalization. 210 | 3) A notification when a channel is FINALIZED after a feature change. 211 | operationId: NotifyConnectionStatus 212 | parameters: 213 | - $ref: "../parameters/_index.yaml#/parameters/provider" 214 | - $ref: "../parameters/_index.yaml#/parameters/environment" 215 | - $ref: "../parameters/_index.yaml#/parameters/interconnect" 216 | - $ref: "../parameters/_index.yaml#/parameters/connection" 217 | requestBody: 218 | content: 219 | application/json: 220 | schema: 221 | $ref: "../schemas/connection.yaml#/NotifyConnectionStatusRequest" 222 | description: The request body. 223 | responses: 224 | default: 225 | content: 226 | application/json: 227 | schema: 228 | $ref: "../schemas/common.yaml#/Empty" 229 | description: Successful operation 230 | security: [] 231 | tags: 232 | - Connections -------------------------------------------------------------------------------- /connection-coordinator/schemas/issues.yaml: -------------------------------------------------------------------------------- 1 | State: 2 | enum: 3 | - STATE_UNSPECIFIED 4 | - STATE_OPEN 5 | - STATE_IN_PROGRESS 6 | - STATE_ACTION_REQUIRED 7 | - STATE_CLOSED 8 | type: string 9 | x-google-enum-descriptions: 10 | - Unspecified state. 11 | - The issue is pending triage. 12 | - The issue is being actively worked on. 13 | - The issue requires action from the requesting provider. 14 | - The issue has been resolved. 15 | Priority: 16 | enum: 17 | - PRIORITY_UNSPECIFIED 18 | - PRIORITY_P0 19 | - PRIORITY_P1 20 | - PRIORITY_P2 21 | - PRIORITY_P3 22 | - PRIORITY_P4 23 | type: string 24 | x-google-enum-descriptions: 25 | - Unspecified priority. 26 | - Highest priority. 27 | - High priority. 28 | - Medium priority. 29 | - Low priority. 30 | - Lowest priority. 31 | IssueContext: 32 | enum: 33 | - ISSUE_CONTEXT_UNSPECIFIED 34 | - ISSUE_CONTEXT_CONNECTION_ISSUE 35 | - ISSUE_CONTEXT_INTERCONNECT_ISSUE 36 | type: string 37 | x-google-enum-descriptions: 38 | - 'Unspecified context, when set the caller may create an issue with arbirary 39 | 40 | content and set context as needed.' 41 | - 'The issue is related to a connection issue. 42 | 43 | 44 | The following context is required: ConnectionContext' 45 | - 'The issue is related to an interconnect issue. 46 | 47 | 48 | The following context is required: InterconnectContext' 49 | ChannelContext: 50 | description: A channel experiencing an issue and any relevant context associated 51 | with it. 52 | properties: 53 | channel: 54 | description: Required. Channel experiencing issues. 55 | type: string 56 | required: 57 | - channel 58 | type: object 59 | 60 | ConnectionContext: 61 | description: 'A connection experiencing an issue and any relevant context associated 62 | with 63 | 64 | it.' 65 | properties: 66 | connection: 67 | description: Required. Connection experiencing issues. 68 | type: string 69 | required: 70 | - connection 71 | type: object 72 | FeatureContext: 73 | description: A feature experiencing an issue and any relevant context associated 74 | with it. 75 | properties: 76 | feature: 77 | description: Required. Feature experincing issues. 78 | type: string 79 | required: 80 | - feature 81 | type: object 82 | InterconnectContext: 83 | description: 'An interconnect experiencing an issue and any relevant context 84 | associated 85 | 86 | with it.' 87 | properties: 88 | interconnect: 89 | description: Required. Interconnect experiencing issues. 90 | type: string 91 | required: 92 | - interconnect 93 | type: object 94 | Issue: 95 | description: 'An issue as expressed by a remote provider related to shared resources 96 | with 97 | 98 | the local provider. 99 | 100 | 101 | Outside of the standard issue fields (body, title, etc), context objects are 102 | 103 | included to allow callers to provide explicit resources associated with the 104 | 105 | issue. These resources may have additional metadata associated with them 106 | to 107 | 108 | further describe the issue. 109 | 110 | 111 | To further standardize the information within a request, the IssueContext 112 | 113 | describes a preset issue type that a provider must be capable of handling. 114 | 115 | This issue type may require specific context be provided in the request. If 116 | 117 | so, the provider may reject the request if that context is not provided.' 118 | properties: 119 | body: 120 | description: Required. Issue body. Core content of the issue. 121 | type: string 122 | channelContexts: 123 | description: Optional. Context associated with channels implicated by this 124 | issue. 125 | items: 126 | $ref: '../schemas/issues.yaml#/ChannelContext' 127 | type: array 128 | connectionContexts: 129 | description: Optional. Context associated with connections implicated by 130 | this issue. 131 | items: 132 | $ref: '../schemas/issues.yaml#/ConnectionContext' 133 | type: array 134 | createTime: 135 | description: Output only. The time the issue was created. 136 | format: date-time 137 | readOnly: true 138 | type: string 139 | featureContexts: 140 | description: Optional. Context associated with features implicated by this 141 | issue. 142 | items: 143 | $ref: '../schemas/issues.yaml#/FeatureContext' 144 | type: array 145 | interconnectContexts: 146 | description: Optional. Context associated with interconnects implicated 147 | by this issue. 148 | items: 149 | $ref: '../schemas/issues.yaml#/InterconnectContext' 150 | type: array 151 | issueContext: 152 | allOf: 153 | - $ref: '../schemas/issues.yaml#/IssueContext' 154 | description: 'Optional. The type of issue associated with resources defined 155 | within the connection 156 | 157 | coordinator.' 158 | localIssueId: 159 | description: 'Output only. Opaque identifier for the local provider. This 160 | identifier allows you to 161 | 162 | interact with the local providers official support API if desired.' 163 | readOnly: true 164 | type: string 165 | name: 166 | description: 'Identifier. The name of the issue resource. 167 | 168 | Format: 169 | 170 | projects/{project}/locations/{location}/providers/{provider}/issues/{issue}' 171 | type: string 172 | x-google-identifier: true 173 | priority: 174 | allOf: 175 | - $ref: '../schemas/issues.yaml#/Priority' 176 | description: Optional. The priority of the issue. 177 | remoteContactEmail: 178 | description: 'Optional. The email address to send all email communications 179 | to in the remote 180 | 181 | provider.' 182 | type: string 183 | remoteIssueId: 184 | description: 'Optional. Opaque identifier for the remote provider. This 185 | identifier allows you to 186 | 187 | interact with the remote providers official support API if desired.' 188 | type: string 189 | state: 190 | allOf: 191 | - $ref: '../schemas/issues.yaml#/State' 192 | description: Output only. The state of the issue. 193 | readOnly: true 194 | title: 195 | description: Required. Issue title. A single line that summarizes the issue. 196 | type: string 197 | required: 198 | - title 199 | - body 200 | type: object 201 | Comment: 202 | description: 'A comment on a issue. 203 | 204 | 205 | Typically comments are a pass through from this API to the remote provider''s 206 | 207 | core support APIs. Therefore, these are not formal resources represented 208 | 209 | within this API and store no state unique to the connection coordinator 210 | 211 | specification.' 212 | properties: 213 | body: 214 | description: Required. The body of the comment. 215 | type: string 216 | createTime: 217 | description: Output only. The time the comment was created. 218 | format: date-time 219 | readOnly: true 220 | type: string 221 | displayName: 222 | description: Output only. The display name of the commenter. 223 | readOnly: true 224 | type: string 225 | localCommentId: 226 | description: 'Output only. Opaque identifier for the local comment. This 227 | identifier allows the caller 228 | 229 | to interact with the local providers official support API if desired.' 230 | readOnly: true 231 | type: string 232 | required: 233 | - body 234 | type: object 235 | AddCommentRequest: 236 | description: Add a comment to an issue. 237 | properties: 238 | comment: 239 | allOf: 240 | - $ref: '../schemas/issues.yaml#/Comment' 241 | description: Required. The comment to add. 242 | required: 243 | - comment 244 | type: object 245 | AddCommentResponse: 246 | description: Results of adding a comment to an issue. 247 | properties: 248 | comment: 249 | allOf: 250 | - $ref: '../schemas/issues.yaml#/Comment' 251 | description: The comment that was added. 252 | type: object 253 | CloseIssueRequest: 254 | description: Request to close an issue. 255 | type: object 256 | CloseIssueResponse: 257 | description: Results of closing an issue. 258 | type: object 259 | ListCommentsResponse: 260 | description: 'List issue comments response body. By default, comments are sorted 261 | by create_time in descending order.' 262 | properties: 263 | comments: 264 | description: The list of Comments 265 | items: 266 | $ref: '../schemas/issues.yaml#/Comment' 267 | type: array 268 | nextPageToken: 269 | description: 'A token that can be sent as `page_token` to retrieve the next 270 | page. 271 | 272 | If this field is omitted, there are no subsequent pages.' 273 | type: string 274 | type: object 275 | ListIssuesResponse: 276 | description: List of issues response body. 277 | properties: 278 | issues: 279 | description: The list of Issue. 280 | items: 281 | $ref: '../schemas/issues.yaml#/Issue' 282 | type: array 283 | nextPageToken: 284 | description: 'A token that can be sent as `page_token` to retrieve the next 285 | page. 286 | 287 | If this field is omitted, there are no subsequent pages.' 288 | type: string 289 | type: object -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | -------------------------------------------------------------------------------- /connection-coordinator/schemas/connection.yaml: -------------------------------------------------------------------------------- 1 | Connection: 2 | description: |- 3 | Connection resources contain all connection wide details about a connection 4 | configured on behalf of a customer between two clouds. 5 | 6 | Connection resources must have the following attributes: 7 | 8 | 1. When created, the connection must reserve bandwidth on their associated 9 | interconnect. 10 | 2. A remote provider must create a connection locally before requesting a 11 | server provider create a connection. 12 | 3. Connections that were never finalized may be deleted by either provider 13 | after 7 days. 14 | 4. Connections present on only one provider may be deleted after 7 days. 15 | 5. When deleted, the server provider is responsible for invalidating the key 16 | material associated with the connection to avoid accidental reuse. 17 | example: 18 | name: name 19 | adminState: "" 20 | activationKey: activationKey 21 | verificationState: "" 22 | bandwidthMbps: 0 23 | properties: 24 | name: 25 | description: Identifier. A unique identifier for the connection resource. 26 | type: string 27 | activationKey: 28 | description: Identifier. A activation key associated with the connection. 29 | type: string 30 | bandwidthMbps: 31 | description: |- 32 | The total bandwidth associated with a connection. This bandwidth is what 33 | has been sold to the customer, there may be more capacity reserved after 34 | provisioning the connection across multiple channels. 35 | format: int32 36 | type: integer 37 | adminState: 38 | allOf: 39 | - $ref: common.yaml#/AdminState 40 | description: Output only. The administrative status of the connection resource. 41 | readOnly: true 42 | verificationState: 43 | allOf: 44 | - $ref: common.yaml#/VerificationState 45 | description: Output only. The verification state of the connection resource. 46 | readOnly: true 47 | type: object 48 | 49 | FeatureGuidance: 50 | description: |- 51 | FeatureGuidance contains a list of preferences and restrictions associated 52 | with feature creation. When fields are unpopulated, the server has no 53 | restrictions or preferences. Unless specified as a preference, the server 54 | provider is expected to reject feature creation requests that deviate from 55 | the feature guidance restrictions returned. 56 | example: 57 | l3BaseGuidance: "" 58 | featureType: "" 59 | channel: channel 60 | properties: 61 | featureType: 62 | allOf: 63 | - $ref: "feature.yaml#/FeatureType" 64 | description: The feature type associated with this guidance. 65 | channel: 66 | description: Relative URI of the Channel this guidance applies to. 67 | type: string 68 | l3BaseGuidance: 69 | allOf: 70 | - $ref: "#/L3BaseGuidance" 71 | description: All configuration guidance associated with a FEATURE_TYPE_L3_BASE. 72 | type: object 73 | 74 | L3BaseGuidance: 75 | description: All guidance associated with the FEATURE_TYPE_L3_BASE. 76 | properties: 77 | asnRanges: 78 | description: |- 79 | A list of non-overlapping ASN ranges a provider can select from. 80 | 81 | Many providers only support one ASN. In this case, asn.start == asn.stop. 82 | items: 83 | $ref: "#/ASNRange" 84 | type: array 85 | ipv4SubnetGuidance: 86 | description: |- 87 | A list of non-overlapping IP subnets a provider can select from. 88 | 89 | Many providers allow connections within the link local IP space. 90 | Example: 91 | 92 | [ 93 | { 94 | "includeSubnet": "169.254.0.0/16", 95 | "excludeSubnet": ["169.254.1.0/28"], 96 | "preferredSubnet":"169.254.1.16/30" 97 | } 98 | ] 99 | items: 100 | $ref: "#/SubnetGuidance" 101 | type: array 102 | ipv6SubnetGuidance: 103 | description: A list of non-overlapping IPv6 subnets a provider can select 104 | from. 105 | items: 106 | $ref: "#/SubnetGuidance" 107 | type: array 108 | ipv4AllowedSubnetPrefixLengths: 109 | description: |- 110 | The subnet sizes allowed when selecting an IP subnet for a connection. 111 | This tells the caller what the valid subnet prefix lengths are within the 112 | subnet guidance provided. Example: If Subnet Guidance is: 113 | [ 114 | { 115 | "includeSubnet": "169.254.0.0/16", 116 | "excludeSubnet": [], 117 | "preferredSubnet":"169.254.1.16/29" 118 | } 119 | ] 120 | And ipv4_allowed_subnet_prefix_lengths is [29] 121 | Then the caller can select a /29 subnet within 169.254.0.0/16. 122 | items: 123 | format: int32 124 | type: integer 125 | type: array 126 | ipv6AllowedSubnetPrefixLengths: 127 | description: |- 128 | The subnet sizes allowed when selecting an IP subnet for a connection. 129 | This tells the caller what the valid subnet prefix lengths are within the 130 | subnet guidance provided. Example: If Subnet Guidance is: 131 | [ 132 | { 133 | "includeSubnet": "fd20::/16", 134 | "excludeSubnet": [], 135 | "preferredSubnet":"fd20:0:0:1::/64" 136 | } 137 | ] 138 | And ipv6_allowed_subnet_prefix_lengths is [64] 139 | Then the caller can select a /64 subnet within fd20::/16. 140 | items: 141 | format: int32 142 | type: integer 143 | type: array 144 | vlanRanges: 145 | description: A list of VLANs the provider may select from. 146 | items: 147 | $ref: "#/VLANRange" 148 | type: array 149 | mtuRanges: 150 | description: |- 151 | A list of non-overlapping MTU ranges a provider can select from. 152 | 153 | Special note: This represents the MTU limits at the connection points 154 | between providers, there may be further limitations within provider 155 | networks that must be explained in customer facing APIs and / or 156 | documentation. 157 | items: 158 | $ref: "#/MTURange" 159 | type: array 160 | maxReceivedBgpRoutePrefixes: 161 | description: |- 162 | Maximum number of BGP route prefixes accepted by the connection. 163 | 164 | While not negotiated between providers, providers must be aware that if 165 | more BGP route prefixes are announced, protocol behavior will be 166 | undefined. 167 | format: int32 168 | type: integer 169 | type: object 170 | 171 | ASNRange: 172 | description: A range of acceptable ASNs. 173 | properties: 174 | start: 175 | description: First ASN (inclusive). 176 | format: int32 177 | type: integer 178 | stop: 179 | description: Last ASN (inclusive). 180 | format: int32 181 | type: integer 182 | type: object 183 | 184 | SubnetGuidance: 185 | description: |- 186 | Guidance for the usable subnets by a provider when provisioning. 187 | 188 | Note: This subnet can be broken down into smaller subnets when 189 | provisioning. 190 | properties: 191 | includeSubnet: 192 | description: A subnet prefix a provider may select within. 193 | type: string 194 | excludeSubnets: 195 | description: |- 196 | A list of subnets that should be excluded when creating a new 197 | feature. 198 | items: 199 | type: string 200 | type: array 201 | preferredSubnet: 202 | description: A subnet preferred by the server when creating a new feature 203 | type: string 204 | type: object 205 | 206 | VLANRange: 207 | description: |- 208 | A range of VLAN IDs that a provider may select from. 209 | 210 | The remote provider should have full visibility into what has been 211 | provisioned from this range. The server will not filter out any used 212 | VLANs on behalf of the caller. 213 | properties: 214 | start: 215 | description: First VLAN (inclusive) 216 | format: int32 217 | type: integer 218 | stop: 219 | description: Last VLAN (inclusive) 220 | format: int32 221 | type: integer 222 | type: object 223 | 224 | MTURange: 225 | description: |- 226 | A range of MTUs that a provider may select from. 227 | 228 | The remote provider should select the highest MTU supported by both 229 | providers. 230 | properties: 231 | start: 232 | description: First MTU (inclusive). 233 | format: int32 234 | type: integer 235 | stop: 236 | description: Last MTU (inclusive). 237 | format: int32 238 | type: integer 239 | type: object 240 | 241 | ListConnectionsResponse: 242 | description: Response for obtaining multiple connection resources. 243 | example: 244 | nextPageToken: nextPageToken 245 | connections: 246 | - name: name 247 | adminState: "" 248 | activationKey: activationKey 249 | verificationState: "" 250 | bandwidthMbps: 0 251 | - name: name 252 | adminState: "" 253 | activationKey: activationKey 254 | verificationState: "" 255 | bandwidthMbps: 0 256 | properties: 257 | connections: 258 | description: The connections from the specified provider. 259 | items: 260 | $ref: "#/Connection" 261 | type: array 262 | nextPageToken: 263 | description: |- 264 | A token, which can be sent as `page_token` to retrieve the next page. 265 | If this field is omitted, there are no subsequent pages. 266 | type: string 267 | type: object 268 | GenerateFeatureGuidanceRequest: 269 | description: |- 270 | Request to generate feature guidance for all channels associated with a 271 | connection. 272 | type: object 273 | GenerateFeatureGuidanceResponse: 274 | description: |- 275 | Response message containing the generated feature guidance for all channels 276 | associated with a connection. 277 | example: 278 | featureGuidance: 279 | - l3BaseGuidance: "" 280 | featureType: "" 281 | channel: channel 282 | - l3BaseGuidance: "" 283 | featureType: "" 284 | channel: channel 285 | properties: 286 | featureGuidance: 287 | description: |- 288 | Output only. A list of guidance a remote provider can use to provision features on the 289 | created connection. The list should include a feature guidance object for 290 | every channel associated with the interconnect the connection is 291 | provisioned on. 292 | items: 293 | $ref: "#/FeatureGuidance" 294 | readOnly: true 295 | type: array 296 | type: object 297 | 298 | NotifyConnectionStatusRequest: 299 | description: |- 300 | A notification from a remote provider that a connection's status has been 301 | updated. 302 | type: object 303 | -------------------------------------------------------------------------------- /connection-coordinator/docs/ConnectionCoordinatorAPI.md: -------------------------------------------------------------------------------- 1 | # Connection Coordinator API 2 | 3 | This document is meant to be a supplement to the OpenAPI specification. Its objective is to provide some clarity around the overall object hierarchy and what each item actually represents. 4 | 5 | ## Primary Object Types 6 | 7 | ### Provider 8 | The base type of `provider` is used to delineate the respective CSP from which requests are being made. For example, as Amazon, we would make requests toward partners using `/providers/aws` as our prefix. This is used as a way of ensuring resource level permissions and isolation server side. 9 | 10 | ### Environment 11 | The `environment` object is used to uniquely describe connectivity between two partner CSPs into specific regions. This is something that the customer would select when creating their connection and would distinctly identify the two regions that are being connected. 12 | 13 | For example, a single `environment` could describe the generic path between (AWS us-east-1) and (GCP us-east4) and another could describe a path (AWS us-west-2) and (GCP us-west1). 14 | 15 | ### Interconnect 16 | The `interconnect` object describes a bundle of `channels` upon which the CSP would place customer `connections`. Each `interconnect` exists as part of an `environment` and each `environment` may have many interconnects. Customers never see the `interconnect` objects, they are solely used by the CSPs. 17 | 18 | The `interconnect` objects reflect the pre-cabled capacity that will be sold to customers and reserved for their use. 19 | 20 | ### Channel 21 | The `channel` object is a single LAG that resides as part of an `interconnect`. There are 4 `channels` per `interconnect`, and each one is a LAG comprising the same number of 100G (or 400G, but must be uniform) ports, resulting in identical capacity on all `channels`. 22 | 23 | ### Connection 24 | The `connection` object represents an explicit customer request for a specific bandwidth across a specific `environment`. After a customer requests a `connection`, our APIs will be used to negotiate the specific `interconnect` to place this `connection` on. The customer has no influence over the `interconnect` choice. 25 | 26 | ### Feature 27 | The `feature` object is an extensible object to describe anything that we may want to support on a given connection. At this time, there is only one feature type, which is Channel Config. 28 | 29 | The Channel Config `feature` is used to convey a negotiated set of L3 parameters including VLAN, IPv4 Subnet, IPv6 Subnet, and MTU. Each of these parameters is negotiated as part of the customer's creation. Once again, the customer has no real influence over the chosen parameters as they are distinctly negotiated between the two CSPs. 30 | 31 | When this Channel config is agreed upon, a hosted connection of the appropriate bandwidth is created on the LAG represented by the `channel`. 32 | 33 | ## Connection Coordination Milestones 34 | 35 | When a customer is looking to create a `Connection` there are 4 major milestones we must achieve: 36 | 37 | 1. Establish Customer Intent 38 | 2. Negotiate Relevant Features Parameters 39 | 3. Provision Relevant Features 40 | 4. Activate Connection 41 | 42 | ## Establish Customer Intent 43 | 44 | To establish this intent, we require that a given customer informs both parties of their desire to create a connection. The standard form of this involves the customer invoking a `CreateConnection` operation on one CSP, and then bringing metadata to the other CSP to perform a pairing `AcceptConnection` operation. 45 | 46 | ### Create Connection at CSP A 47 | 48 | The customer needs to make a call to the appropriate API on CSP A, specifically the API which performs the function of `CreateConnection`. Worth noting that this functionality is required at each CSP, but the specification does not set out any specific API names of constructs that must be used. 49 | 50 | Overall, this `CreateConnection` operation needs to determine at least the following information: 51 | - Remote CSP Account ID 52 | - Environment 53 | - Bandwidth 54 | 55 | #### Rmote CSP Account ID 56 | 57 | When creating the connection, the customer must supply a means of identifying which account on the other CSP they intend to connect. In the case of AWS, this would be the account number, and in the case of GCP, this would be the Project Name. This is used to ensure that only a single destination account can accept the details of this specific connection when it is time for the later confirmation step. 58 | 59 | #### Environment Choice 60 | 61 | The `Environment` dictates which CSPs and regions the resulting connection will span. The specific `Environment` choice may also represent the selection of a specific additional quality in the underlying connection--no such additional qualities exist at this time, but this is the scope at which the distinction would be made. 62 | 63 | #### Bandwidth Choice 64 | 65 | Once the specific `Environment` is known, the user can also select their desired bandwidth. Bandwidth is offered at discrete tiers, and each specific `Environment` may offer a different set of selections. The permissible set of bandwidths is laid out within the specification itself. 66 | 67 | #### Activation Key 68 | 69 | The net result of a call to this API is to create a pending `Connection` object in CSP A and to return to the customer an `ActivationKey`. This `ActivationKey` contains details about the underlying connection parameters set out by the customer in this call. 70 | 71 | Note that to this point, no calls have been made from CSP A to CSP B--that won't happen until after the customer gives CSP B the `ActivationKey` 72 | 73 | ### Accept Connection at CSP B 74 | 75 | With the `ActivationKey` from CSP A in hand, the customer needs to go login to CSP B. Here they will call the appropriate API serving the function of `AcceptConnection`. This API needs to take in the `ActivationKey`. CSP B should read the details out of the `ActivationKey` and provide that information to the customer so they can confirm that the information looks correct. 76 | 77 | Assuming the customer accepts the details, the `Connection` object on CSP B can be created in a pending state--this object is tentative pending successful confirmation. 78 | 79 | ### Confirming the Activation Key 80 | 81 | Notice that in the above step, CSP B did not yet ask CSP A if the `ActivationKey` was real. While we may have already created a stand-in customer object on CSP B, we must still ask CSP A to confirm that the provided `ActivationKey` is in fact real. 82 | 83 | This is done using the `ConfirmActivationKey` API scoped to the desired environment. If CSP A responds to this request with success, then we can claim that we have completely established the customer's intent. 84 | 85 | ## Negotiate Relevant Features Parameters 86 | 87 | For the purposes of a negotiation phase, one CSP is considered the "Negotiator" while the other is considered the "Responder". The Negotiator will make proposals to fulfill specific needs, and the Responder either accepts or rejects the proposals in full. 88 | 89 | ### Negotiation: Interconnect Selection 90 | 91 | The first step in the negotiate workflow is to select the appropriate `Interconnect`. This value is proposed by effectively "creating" the `Connection` object as a resource underneath that proposed `Interconnect`. If this interconnect is not acceptable, then it should fail the creation with `409 CONFLICT`. 92 | 93 | In general, the conflict result should only be used for cases in which the selected `Interconnect` cannot fit the required bandwidth. This should only occur in cases where there is a race between the two sides (i.e. multiple creations at the same time started on separate CSPs). 94 | 95 | If there was a `409 CONFLICT` response, the Negotiator should select a different `Interconnect` which is part of the same `Environment` and retry the initial request. 96 | 97 | ### Negotiate L3 Parameters 98 | 99 | After selecting the `Interconnect` each CSP now knows which sets of hardware/ports are to be used when placing the specific customer `Connection`. With this info, we are able to start the L3 Parameter negotiations. 100 | 101 | Each `Interconnect` contains a certain number of `Channels` (optimally 4), and the negotiation process for each of these channels is looking to create a `Feature` that contains the L3 Config for a specific `Channel`. 102 | 103 | The parameter selection process is designed to be done separately for each of the necessary channels. The following sample showcases the negotiation workflow for a single channel. 104 | 105 | The general Negotiation paradigm is that when an attempt to create a `Feature` occurs, the Responder either Accepts the `Feature` in full or rejects it. 106 | 107 | #### Step 1: Request FeatureGuidance 108 | 109 | The first step in the process is for the Negotiator to ask the Responder for any guidance that should be taken into consideration. Since the Negotiator must proposed the ENTIRE `Feature` all at once, this is useful for determining the parameters which the other CSP would not know ahead of time. Note, the guidance itself is requested on the `Connection` object, and the response will provide guidance for each desired `Feature` independently. 110 | 111 | In general, the guidance includes details for each `Feature` such as: 112 | - ASN of the remote network 113 | - MTU 114 | - IPv4/IPv6 details 115 | 116 | The IPv4 and IPv6 details provide narrowing semantics around the BGP peering parameters that will be negotiated, specifically a large subnet of "acceptable" space, with smaller subnets of exclusions. 117 | 118 | 119 | #### Step 2: Negotiate L3 Parameters 120 | 121 | Once the `FeatureGuidance` has been received, we can start to submit actual negotiation attempts for the L3 Configuration. While the previous `FeatureGuidance` was requested once for the connection on all channels, the L3 Parameter negotiation is intended to be done on a per-channel basis as this is deemed overall to be more flexible than trying to use the same parameters across all channels. 122 | 123 | The process of creating a `Feature` involves quite literally creating a `Feature` object on the corresponding `Connection`, using the `CreateFeature` operation. A successful creation will elicit a 200 response. 124 | 125 | If something is not quite right, then the responder should reject the configuration with `409 Conflict`. Upon receiving the 409, the negotiator should restart this channel's workflow from the `FeatureGuidance` step above, making use of the form which includes query params channelId and featureType. 126 | 127 | Once all desired features have been created, we can move onto provisioning the actual hardware. 128 | 129 | ## Provision Relevant Features 130 | 131 | With all Features in place and agreed upon, each CSP now looks to handle the necessary provisioning on their respective internal systems. This operation is not necessarily guaranteed to be quick, and CSPs should be prepared as such. 132 | 133 | After local provisioning is complete, each CSP can independently move onto the final step, Activate Connection. 134 | 135 | ## Activate Connection 136 | 137 | Once all provisioning is done, each CSP can indicate that the connection has become active by setting the `VerificationState` accordingly. Additionally, they must call `NotifyConnectionStatus` API to inform the other CSP of the status change. 138 | 139 | From here, all customer routes should be exchanged and connectivity established. --------------------------------------------------------------------------------