Run on Amazon Elastic Container Service (ECS)
The following is an example task definition for running topaz on Amazon ECS using either Fargate or EC2 as a capacity provider.
This example includes an init-config container that is responsible for retrieving a topaz config file from
an S3 bucket before the topaz container starts up.
The topaz config new CLI command can be used to generate
your configuration file, then it should be uploaded to a bucket location that is accessible by the init-config container.
If you intend to access the topaz console from a browser, you need to edit the generated configuration file and:
- Set the
fqdn(fully-qualified domain name) field in all gateway services to the DNS name and port of the topaz instance. - Add your domain to the list of
allowed_originsfor all services.
The fqdn fields should be set to an https:// url with the hostname of the topaz instance and the port on which the
gateway service is exposed.
For example, if you are running the topaz container with the topaz.example.com DNS name and the default ports, you
would set the authorizer service's gateway to fqdn: https://topaz.example.com:8383 and the directory services's
(reader, writer, model, importer, exporter) gateways to fqdn: https://topaz.example.com:9393.
In addition, you would add your domain the allowed_origins list:
allowed_origins:
- https://localhost
- https://localhost:*
- https://topaz.example.com
- https://topaz.example.com:*
This example attaches an EBS volume to persist the configuration, certs, and directory database. If it does not already exist you may need to create an IAM ECS Infrastructure Role to allow ECS to provision EBS volumes.
Certificates
By default, topaz generates its own self-signed TLS certificates if none are provided. Those certificates are not trusted by browsers and prevent the topaz console from communicating with the service. There are two ways around it:
Trust the self-signed certificates
You can download the generated certificate from the topaz instance using a browser or from the terminal using openssl:
openssl s_client -showcerts -connect <topaz_hostname>:8383 </dev/null 2>/dev/null | \
openssl x509 -text > topaz-gateway.crt
This downloads the certificate from the specified topaz instance address and saves it to a local file
named topaz-gateway.crt. You can then add the certificate to your system's trust store.
To download the gRPC certificate, replace the port number with 8282:
openssl s_client -showcerts -connect <topaz_hostname>:8282 </dev/null 2>/dev/null | \
openssl x509 -text > topaz-grpc.crt
Use your own certificates
You can issue your own certificates and mount them into the /data/certs directory in the topaz container.
There should be two certificates, one used for by the gRPC services and the other for REST.
You should have six files in total:
grpc.key: private key for the gRPC servicesgrpc.crt: public certificate for the gRPC servicesgrpc-ca.crt: CA certificate for the gRPC servicesgateway.key: private key for the REST servicesgateway.crt: public certificate for the REST servicesgateway-ca.crt: CA certificate for the REST services
Sample task definition for topaz on Amazon ECS
Using the ECS console, create a task definition with existing JSON. You will need to modify the init container environment variables in this task definition with credentials that can reach your configuration bucket as well as executionRoleArn with a value appropriate for your account.
{
"containerDefinitions": [
{
"name": "init-config",
"image": "amazonlinux:latest",
"cpu": 0,
"portMappings": [],
"essential": false,
"entryPoint": [
"sh",
"-ex",
"-c"
],
"command": [
"dnf install awscli -yq; aws s3 cp s3://${TOPAZ_CONFIG_BUCKET}/config.yaml /data/config/config.yaml;"
],
"environment": [
{
"name": "AWS_ACCESS_KEY_ID",
"value": "<YOUR ACCESS KEY ID>"
},
{
"name": "AWS_SECRET_ACCESS_KEY",
"value": "<YOUR SECRET ACCESS KEY>"
},
{
"name": "TOPAZ_CONFIG_BUCKET",
"value": "<YOUR BUCKET NAME>"
}
],
"environmentFiles": [],
"mountPoints": [
{
"sourceVolume": "data",
"containerPath": "/data",
"readOnly": false
}
],
"volumesFrom": [],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "/ecs/topaz",
"awslogs-region": "us-east-2",
"awslogs-stream-prefix": "ecs"
},
"secretOptions": []
}
},
{
"name": "topaz",
"image": "ghcr.io/aserto-dev/topaz:latest",
"cpu": 0,
"portMappings": [
{
"name": "console-http",
"containerPort": 8080,
"hostPort": 8080,
"protocol": "tcp",
"appProtocol": "http"
},
{
"name": "console-grpc",
"containerPort": 8081,
"hostPort": 8081,
"protocol": "tcp",
"appProtocol": "grpc"
},
{
"name": "authorizer-grpc",
"containerPort": 8282,
"hostPort": 8282,
"protocol": "tcp",
"appProtocol": "grpc"
},
{
"name": "authorizer-http",
"containerPort": 8383,
"hostPort": 8383,
"protocol": "tcp",
"appProtocol": "http"
},
{
"name": "directory-grpc",
"containerPort": 9292,
"hostPort": 9292,
"protocol": "tcp",
"appProtocol": "grpc"
},
{
"name": "directory-http",
"containerPort": 9393,
"hostPort": 9393,
"protocol": "tcp",
"appProtocol": "http"
},
{
"name": "healthcheck",
"containerPort": 9494,
"hostPort": 9494,
"protocol": "tcp",
"appProtocol": "http"
},
{
"name": "metrics",
"containerPort": 9696,
"hostPort": 9696,
"protocol": "tcp",
"appProtocol": "http"
}
],
"essential": true,
"entryPoint": [
"sh",
"-ex",
"-c"
],
"command": [
"mkdir -p ${TOPAZ_CERTS_DIR}; ./topazd run -c ${TOPAZ_CONFIG_DIR}/config.yaml"
],
"environment": [
{
"name": "TOPAZ_CONFIG_DIR",
"value": "/data/config"
},
{
"name": "TOPAZ_CERTS_DIR",
"value": "/data/certs"
},
{
"name": "TOPAZ_DB_DIR",
"value": "/data/db"
}
],
"environmentFiles": [],
"mountPoints": [
{
"sourceVolume": "data",
"containerPath": "/data",
"readOnly": false
}
],
"volumesFrom": [],
"dependsOn": [
{
"containerName": "init-config",
"condition": "SUCCESS"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "/ecs/topaz",
"awslogs-region": "us-east-2",
"awslogs-stream-prefix": "ecs"
},
"secretOptions": []
}
}
],
"family": "topaz",
"executionRoleArn": "arn:aws:iam::xxx:role/ecsTaskExecutionRole",
"networkMode": "awsvpc",
"volumes": [
{
"name": "data",
"configuredAtLaunch": true
}
],
"placementConstraints": [],
"requiresCompatibilities": [
"FARGATE",
"EC2"
],
"cpu": "256",
"memory": "2048",
"runtimePlatform": {
"cpuArchitecture": "X86_64",
"operatingSystemFamily": "LINUX"
}
}
From here you can launch topaz by creating a new service in your ECS cluster.