Exoscale security-group API
Security Groups are groups of firewall rules that regulate network traffic to and from your Compute instances.
OpenAPI Specification
openapi: 3.0.0
info:
version: 2.0.0
termsOfService: https://exoscale.com/terms
contact:
email: support@exoscale.com
name: Exoscale Support
url: https://portal.exoscale.com/tickets
title: Exoscale ai-api-key security-group API
description: Infrastructure automation API, allowing programmatic access to all Exoscale products and services.
servers:
- url: https://api-{zone}.exoscale.com/v2
variables:
zone:
default: ch-gva-2
enum:
- ch-gva-2
- ch-dk-2
- de-fra-1
- de-muc-1
- at-vie-1
- at-vie-2
- bg-sof-1
- hr-zag-1
tags:
- description: "Security Groups are groups of firewall rules that regulate\n network traffic to and from your Compute instances."
parent: compute
externalDocs:
description: Read more
url: https://community.exoscale.com/documentation/compute/security-groups/
name: security-group
x-display-name: Security Group
x-weight: 150
x-icon: exo-vpc
paths:
/security-group/{id}/rules/{rule-id}:
delete:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: rule-id
schema:
type: string
format: uuid
summary: Delete a Security Group rule
operationId: delete-rule-from-security-group
/security-group:
post:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters: []
summary: Create a Security Group
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
description: Security Group name
description:
type: string
maxLength: 255
description: Security Group description
required:
- name
operationId: create-security-group
get:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
security-groups:
type: array
items:
$ref: '#/components/schemas/security-group'
description: 'Lists security groups. When visibility is set to public, lists public security groups.
Public security groups are objects maintained by Exoscale which contain source addresses for
relevant services hosted by Exoscale. They can be used a source in ingress rules and as a destination
in egress rules.'
parameters:
- in: query
required: false
name: visibility
schema:
type: string
enum:
- private
- public
summary: List Security Groups.
operationId: list-security-groups
/security-group/{id}:
get:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/security-group'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Retrieve Security Group details
operationId: get-security-group
delete:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Delete a Security Group
operationId: delete-security-group
/security-group/{id}:attach:
put:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Attach a Compute instance to a Security Group
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
instance:
$ref: '#/components/schemas/instance'
description: Compute instance
required:
- instance
operationId: attach-instance-to-security-group
/security-group/{id}/rules:
post:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Create a Security Group rule
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
flow-direction:
type: string
enum:
- ingress
- egress
description: Network flow direction to match
description:
type: string
maxLength: 255
description: Security Group rule description
network:
type: string
description: CIDR-formatted network allowed
security-group:
$ref: '#/components/schemas/security-group-resource'
description: Security Group allowed
protocol:
type: string
enum:
- tcp
- esp
- icmp
- udp
- gre
- ah
- ipip
- icmpv6
description: Network protocol
icmp:
type: object
properties:
code:
type: integer
format: int64
minimum: -1
maximum: 254
exclusiveMinimum: false
exclusiveMaximum: false
nullable: true
type:
type: integer
format: int64
minimum: -1
maximum: 254
exclusiveMinimum: false
exclusiveMaximum: false
nullable: true
description: 'ICMP details (default: -1 (ANY))'
start-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Start port of the range
end-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: End port of the range
required:
- flow-direction
- protocol
operationId: add-rule-to-security-group
/security-group/{id}:remove-source:
put:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Remove an external source from a Security Group
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cidr:
type: string
description: CIDR-formatted network to remove
required:
- cidr
operationId: remove-external-source-from-security-group
/security-group/{id}:detach:
put:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Detach a Compute instance from a Security Group
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
instance:
$ref: '#/components/schemas/instance'
description: Compute instance
required:
- instance
operationId: detach-instance-from-security-group
/security-group/{id}:add-source:
put:
tags:
- security-group
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Add an external source as a member of a Security Group
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cidr:
type: string
description: CIDR-formatted network to add
required:
- cidr
operationId: add-external-source-to-security-group
components:
schemas:
instance-type:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Instance type ID
size:
type: string
enum:
- large
- huge
- jumbo
- medium
- mega
- small
- extra-large
- titan48c
- titan
- micro
- colossus
- tiny
readOnly: true
description: Instance type size
family:
type: string
enum:
- gpu3
- gpua30
- gpu3080ti
- gpu2
- gpu
- memory
- gpua5000
- gpurtx6000pro
- storage
- standard
- colossus
- cpu
readOnly: true
description: Instance type family
cpus:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
readOnly: true
description: CPU count
gpus:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
readOnly: true
description: GPU count
authorized:
type: boolean
readOnly: true
description: Requires authorization or publicly available
memory:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
readOnly: true
description: Available memory
zones:
type: array
items:
$ref: '#/components/schemas/zone-name'
readOnly: true
description: Instance Type available zones
description: Compute instance type
ssh-key:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
x-go-findable: '1'
description: SSH key name
fingerprint:
type: string
readOnly: true
x-go-findable: '2'
description: SSH key fingerprint
description: SSH key
labels:
type: object
additionalProperties:
type: string
deploy-target-ref:
type: object
properties:
id:
type: string
format: uuid
description: Deploy target ID
description: Deploy target reference
security-group-ref:
type: object
properties:
id:
type: string
format: uuid
description: Security group ID
description: Security group reference
anti-affinity-group-ref:
type: object
properties:
id:
type: string
format: uuid
description: Anti-affinity group ID
description: Anti-affinity group reference
security-group-rule:
type: object
properties:
description:
type: string
maxLength: 255
description: Security Group rule description
start-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Start port of the range
protocol:
type: string
enum:
- tcp
- esp
- icmp
- udp
- gre
- ah
- ipip
- icmpv6
description: Network protocol
icmp:
type: object
properties:
code:
type: integer
format: int64
minimum: -1
maximum: 254
exclusiveMinimum: false
exclusiveMaximum: false
type:
type: integer
format: int64
minimum: -1
maximum: 254
exclusiveMinimum: false
exclusiveMaximum: false
description: ICMP details
end-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: End port of the range
security-group:
$ref: '#/components/schemas/security-group-resource'
description: Security Group allowed
id:
type: string
format: uuid
readOnly: true
description: Security Group rule ID
network:
type: string
description: CIDR-formatted network allowed
flow-direction:
type: string
enum:
- ingress
- egress
description: Network flow direction to match
description: Security Group rule
template:
type: object
properties:
application-consistent-snapshot-enabled:
type: boolean
description: Template with Qemu Guest Agent installed for application consistent snapshot
maintainer:
type: string
readOnly: true
description: Template maintainer
description:
type: string
maxLength: 255
description: Template description
ssh-key-enabled:
type: boolean
description: Enable SSH key-based login
family:
type: string
readOnly: true
description: Template family
name:
type: string
maxLength: 255
minLength: 1
description: Template name
default-user:
type: string
maxLength: 255
minLength: 1
description: Template default user
size:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
description: Template size
password-enabled:
type: boolean
description: Enable password-based login
build:
type: string
readOnly: true
description: Template build
checksum:
type: string
description: Template MD5 checksum
boot-mode:
type: string
enum:
- legacy
- uefi
description: 'Boot mode (default: legacy)'
id:
type: string
format: uuid
readOnly: true
description: Template ID
zones:
type: array
items:
$ref: '#/components/schemas/zone-name'
description: Zones availability
url:
type: string
description: Template source URL
version:
type: string
readOnly: true
description: Template version
created-at:
type: string
format: date-time
readOnly: true
description: Template creation date
visibility:
type: string
enum:
- private
- public
readOnly: true
description: Template visibility
description: Instance template
zone-name:
type: string
enum:
- ch-dk-2
- de-muc-1
- ch-gva-2
- at-vie-1
- de-fra-1
- bg-sof-1
- at-vie-2
- hr-zag-1
elastic-ip-ref:
type: object
properties:
id:
type: string
format: uuid
description: Elastic IP ID
description: Elastic IP reference
manager:
type: object
properties:
id:
type: string
format: uuid
description: Manager ID
type:
type: string
enum:
- sks-nodepool
- instance-pool
description: Manager type
description: Resource manager
security-group:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Security Group ID
name:
type: string
maxLength: 255
minLength: 1
description: Security Group name
description:
type: string
maxLength: 255
description: Security Group description
external-sources:
type: array
items:
type: string
uniqueItems: true
description: Security Group external sources
rules:
type: array
items:
$ref: '#/components/schemas/security-group-rule'
uniqueItems: true
writeOnly: true
description: Security Group rules
description: Security Group
public-ip-assignment:
type: string
enum:
- inet4
- dual
- none
instance-state:
type: string
enum:
- expunging
- starting
- destroying
- running
- stopping
- stopped
- migrating
- error
- destroyed
instance:
type: object
properties:
application-consistent-snapshot-enabled:
type: boolean
description: Indicates if the instance will take application-consistent snapshots
anti-affinity-groups:
type: array
items:
$ref: '#/components/schemas/anti-affinity-group-ref'
description: Instance Anti-affinity Groups
public-ip-assignment:
$ref: '#/components/schemas/public-ip-assignment'
description: Instance public IP assignment
labels:
$ref: '#/components/schemas/labels'
description: Resource labels
security-groups:
type: array
items:
$ref: '#/components/schemas/security-group-ref'
description: Instance Security Groups
elastic-ips:
type: array
items:
$ref: '#/components/schemas/elastic-ip-ref'
description: Instance Elastic IPs
name:
type: string
maxLength: 255
minLength: 1
description: Instance name
instance-type:
$ref: '#/components/schemas/instance-type'
description: Instance Type
private-networks:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Private Network ID
mac-address:
type: string
description: Private Network MAC address
description: Private Network
description: Instance Private Networks
template:
$ref: '#/components/schemas/template'
description: Instance Template
state:
$ref: '#/components/schemas/instance-state'
readOnly: true
description: Instance state
secureboot-enabled:
type: boolean
description: Indicates if the instance has secure boot enabled
ssh-key:
$ref: '#/components/schemas/ssh-key'
description: Instance SSH Key
user-data:
type: string
minLength: 1
description: Instance Cloud-init user-data (base64 encoded)
mac-address:
type: string
readOnly: true
description: Instance MAC address
manager:
$ref: '#/components/schemas/manager'
readOnly: true
description: Instance manager
tpm-enabled:
type: boolean
description: Indicates if the instance has tpm enabled
deploy-target:
$ref: '#/components/schemas/deploy-target-ref'
description: Instance Deploy Target
ipv6-address:
type: string
readOnly: true
description: Instance IPv6 address
id:
type: string
format: uuid
readOnly: true
description: Instance ID
snapshots:
type: array
items:
$ref: '#/components/schemas/snapshot-ref'
description: Instance Snapshots
disk-size:
type: integer
format: int64
minimum: 10
maximum: 51200
exclusiveMinimum: false
exclusiveMaximum: false
description: Instance disk size in GiB
ssh-keys:
type: array
items:
$ref: '#/components/schemas/ssh-key'
description: Instance SSH Keys
created-at:
type: string
format: date-time
readOnly: true
description: Instance creation date
public-ip:
type: string
format: ipv4
readOnly: true
description: Instance public IPv4 address
description: Instance
snapshot-ref:
type: object
properties:
id:
type: string
format: uuid
description: Snapshot ID
description: Snapshot reference
operation:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Operation ID
reason:
type: string
enum:
- incorrect
- unknown
- unavailable
- forbidden
- busy
- fault
- partial
- not-found
- interrupted
- unsupported
- conflict
readOnly: true
description: Operation failure reason
reference:
type: object
properties:
id:
type: string
format: uuid
description: Reference ID
link:
type: string
readOnly: true
description: Link to the referenced resource
command:
type: string
description: Command name
description: Related resource reference
readOnly: true
message:
type: string
readOnly: true
description: Operation message
state:
type: string
enum:
- failure
- pending
- success
- timeout
readOnly: true
description: Operation status
description: Operation
security-group-resource:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Security Group ID
name:
type: string
maxLength: 255
minLength: 1
description: Security Group name
visibility:
type: string
enum:
- private
- public
description: "Whether this points to a public security group. This is only valid when in the context of\n a rule addition which uses a public security group as a source or destination."
description: Security Group
x-topics:
- title: API Request Signature
content: '
In order to authenticate legitimate users, the Exoscale API requires incoming requests to be signed using valid Exoscale API account credentials with the following mechanism.
## Signature Mechanism
The *message* (i.e. content) to sign contains several segments concatenated using a line return character (`\n`).
All segments must be included and in the described order. For cases where a segment doesn''t fit the context of the request (e.g. no request body) **an empty line must be used instead**.
* Request method and request URL (path only), separated by a space character
* Request body
* Request URL parameters (Query String) values, concatenated without separator. The matching parameter names have to be specified in the resulting signature header `signed-query-args=` pragma, separated by semicolons (e.g. `p1;p2;pN`).
* Request header values, concatenated without separator (none at the moment, leave empty)
* Request expiration date in UNIX timestamp format
Example *message* to sign for `GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2`:
```
GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0
v1v2
1599140767
```
The two blank lines above are due to the absence of a request body and signed headers.
Example *message* to [create a security group](https://community.exoscale.com/reference/api/compute/security-group/#create-security-group)
```
POST /v2/security-group
{"name": "my-security-group"}
1599140767
```
The two blank lines above are due to the absence of query parameters and signed headers.
The request signature consists of the base64-encoded [HMAC](https://en.wikipedia.org/wiki/HMAC) hash of the UTF-8 encoded *message* and the Exoscale API secret using the SHA265 function:
```
signature = BASE64_ENCODE(HMAC_SHA256(Exoscale API secret, message))
```
Finally, the computed signature must be added to the API request in a `Authorization` header such as:
```
Authorization: EXO2-HMAC-SHA256 credential=<Exoscale API key>,expires=<expiration date UNIX timestamp>,signature=<signature>
```
Example API query:
```
GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2 HTTP/1.1
Host: api-ch-gva-2.exoscale.com
Authorization: EXO2-HMAC-SHA256 credential=EXO29147e9f89102b7ac1e88514,signed-query-args=p1;p2,expires=1599140767,signature=2AOBQsbElQb4FpKT/FM/9T4NobjlmZkSGvvdUth/xlY=
```
## Reference Implementations
You can look up the following existing reference implementations:
* Go: [github.com/exoscale/egoscale/api/v2 > `SecurityProviderExoscale.signRequest`](https://github.com/exoscale/egoscale/blob/master/v2/api/security.go)
* Python: [requests-exoscale-auth > `ExoscaleV2Auth`](https://github.com/exoscale/requests-exoscale-auth/blob/master/exoscale_auth.py)
'
- title: Zone local resources
content: '
The API is deployed across all Exoscale zones. When performing a compute call, you should use the relevant zone for your resource.
For example: https://api-de-fra-1.exoscale.com/v2/instance would return only the instances from `de-fra-1`, https://api-ch-gva-2.exoscale.com/v2/instance from `ch-gva-2`.
To obtain a list of all instances across all zones, you would need to do the corresponding request for each zone.
'