Skip to main content

Integrate an SQS queue as a service

In this guide, you’ll learn how to define an SQS queue as a reusable service in nullplatform. This allows you to manage it centrally and link it to other entities.

  1. Craft a service specification for your SQS queue, including:
    • Its attributes, dimensions, and visibility settings
    • Standard lifecycle actions (create, update, delete)
  2. Create a link specification to enable connections between the SQS service and other platform entities.

1. Craft your service specification​

The example below shows how to craft a simple SQS service specification tailored to your organization's settings.

You can create a service specification using our CLI or API.

np service-specification create \
  --body '{
  "name": "SQS Queue",
  "type": "dependency",
  "visible_to": [
    "organization=1234:account=*"
  ],
  "dimensions": {
    "country": {
      "required": true
    },
    "environment": {
      "required": true
    }
  },
  "assignable_to": "dimension",
  "use_default_actions": true,
  "attributes": {
    "schema": {
      "type": "object",
      "required": [
        "queue_arn",
        "queue_url"
      ],
      "properties": {
        "queue_arn": {
          "type": "string",
          "title": "Queue ARN",
          "export": true,
          "pattern": "^arn:aws:sqs:[a-z0-9-]+:[0-9]+:([a-zA-Z0-9_-]+\\.fifo|[a-zA-Z0-9_-]+)$",
          "visibleOn": ["read", "update"],
          "editableOn": []
        },
        "queue_url": {
          "type": "string",
          "title": "Queue URL",
          "export": true,
          "visibleOn": ["read", "update"],
          "editableOn": []
        },
        "account_id": {
          "type": "string",
          "title": "AWS Account ID",
          "config": {
            "key": "aws.account_id"
          },
          "export": false,
          "readOnly": true,
          "visibleOn": ["read"],
          "editableOn": []
        },
        "delay_seconds": {
          "type": "integer",
          "title": "Delay Seconds",
          "maximum": 900,
          "minimum": 0,
          "description": "The time in seconds to delay the delivery of new messages (0-900). Only available for standard queues.",
          "visibleOn": ["read", "create", "update"],
          "editableOn": ["create", "update"]
        },
        "dead_letter_arn": {
          "type": "string",
          "title": "Dead Letter Queue ARN",
          "export": true,
          "pattern": "^arn:aws:sqs:[a-z0-9-]+:[0-9]+:([a-zA-Z0-9_-]+\\.fifo|[a-zA-Z0-9_-]+)$",
          "visibleOn": ["read"],
          "editableOn": []
        },
        "visibility_timeout": {
          "type": "integer",
          "title": "Visibility Timeout",
          "maximum": 43200,
          "minimum": 0,
          "description": "The length of time (in seconds) that a message will be invisible to other receiving components",
          "visibleOn": ["read", "update"],
          "editableOn": ["update"]
        }
      },
      "additionalProperties": false
    },
    "values": {}
  },
  "selectors": {
    "category": "Messaging Services",
    "imported": false,
    "provider": "AWS",
    "sub_category": "Message Queue"
  }
}'
Request details

  • visible_to: This service is visible to all accounts (account=*) within organization 1234.

  • use_default_actions: Enables the default set of actions (such as create, update, and delete) for this service.

  • attributes specify the required connection and configuration details needed by applications that interact with the SQS queue:

    • queue_arn: The Amazon Resource Name (ARN) of the SQS queue. This uniquely identifies the queue and must follow the SQS ARN format. It is exported for use in downstream services and visible during read and update operations.
    • queue_url: The full URL of the queue, used by applications to send and receive messages. Like the ARN, it is exported and visible on read and update actions.
    • account_id: The ID of the AWS account where the queue is located. It is automatically set, read-only, and not exported.
    • delay_seconds: The number of seconds to delay the delivery of new messages to the queue. This only applies to standard queues and must be between 0 and 900. Editable during creation and updates.
    • dead_letter_arn: The ARN of an optional dead letter queue to which messages that can't be processed successfully are sent. This helps with debugging and message handling failures. It is exported and visible on read.
    • visibility_timeout: The number of seconds during which a received message remains invisible to other consumers. This setting helps avoid message duplication and should be adjusted based on your processing logic.

  • Special schema keys:

    • visibleOn: Controls when a property is shown in the UI. For example, read, create, or update.
    • editableOn: Controls when a property can be edited. For example, create, or update. If the array is empty, the property won't be editable in any stage of the instance lifecycle.

For more details, refer to Create service specification in our API docs.

Now that the service spec is created together with standard actions, you can go ahead and create the link specification for the service.

As with service specs, you can craft link specs using our CLI or our API.

np link_specification create \
  --body '{
    "name": "Link SQS queue",
    "unique": false,
    "specification_id": "f3da5e42-87cb-49d3-b108-4c6b9fd7202b",
    "attributes": {
      "type": "object",
      "properties": {},
      "required": []
    }
  }'

In this example, a link for an SQS service is defined with no attributes because the link spec is only needed to sync the service attributes with its parameters.

For more details, refer to Create a link specification in our API docs.

Security and permissions​

Each defined element comes with its own permissions and access control, allowing for the management of who can create and use resources and where these resources can be deployed.