Services

This section is under construction

We're building documentation for this section.

What is a Service?

A service refers to any dependency an application requires for operation. These dependencies can include databases, caches, and can exist in on-premises environments or as part of a cloud service. Services can also encompass other types of dependencies such as monitoring software, email services, or even other applications. This broad definition means that virtually any definable element required for an application’s operation can be considered a service.

Purpose of Services

Services manage several critical aspects of application and resource lifecycle, including:

• Provisioning: Handles the provisioning of new resources or the integration of existing ones into an application or other entity.

• Cataloging: Constructs a catalog of dependencies for each application (or other entities), which helps maintain traceability between applications and services usage.

• Configuration Injection: Automatically injects and manages the parameters of these resources in the applications that use them within the appropriate environments.

• Updates: Allows services to be updated to new versions in a controlled and secure manner.

Key Concepts

Services and Links

• Service: Represents the declaration of an application dependency (or dependency of another entity), containing associated service data. For example, a statement that an application relies on a database or cache.

• Link: A mechanism through which a service is linked to an application (or another entity). This link might be subject to various conditions, often related to the scope or environment. For example, an application may use one database schema in a development environment and a different schema in production, with each configuration maintained independently.

Example MySQL Service Integration

This example illustrates the configuration and usage of a MySQL service within an application. The service configuration references an instance of the MySQL database engine with specific attributes necessary for connectivity and operation.

Service: MySQL Database Engine

• Attributes:
  • Host: Specifies the server address where the MySQL database is hosted.
  • Port: Defines the port number through which the MySQL database accepts connections.

Links: Development and Production Environments

The service is linked to the application through two distinct profiles, catering to different stages of the application lifecycle:

1. Development Link

• Properties:
  • Database: Name of the database used in the development environment.
  • Username: Credential for accessing the MySQL database in development.
  • Password: Password associated with the username for development access.

2. Production Link

• Properties:
  • Database: Name of the database used in the production environment.
  • Username: Credential for accessing the MySQL database in production.
  • Password: Password associated with the username for production access.

Automatic Parameter Integration

When an application establishes a link to the MySQL service, all necessary parameters are automatically generated and integrated within the application's configuration. These parameters include:

• Host: Derived from the service's host attribute.
• Port: Derived from the service's port attribute.
• User: Specified by the link's username property.
• Pass: Specified by the link's password property.
• Name: Specified by the link's database property.

This setup demonstrates a structured approach to managing database connectivity in different environments through service and link specifications. By defining these attributes and links, applications can dynamically adapt their configuration based on the target environment, ensuring that development and production settings are managed separately yet efficiently.

Specifications

• Service Specification: Involves setting attributes and constraints that a service must meet, along with basic actions like creation, update, and deletion of a service. Attributes of a service, such as host and port for a database, are defined using JSON Schema.

  Example MySQL Service Specification

  {
    "name": "MySQL",
    "visible_to": ["organization=12345:account=12345:namespace=28"],
    "attributes" : {
      "schema": {
        "type": "object",
        "required": ["host", "port"],
        "properties": {
          "host": {
            "type": "string",
            "export": true,
            "readOnly": true
          },
          "port": {
            "type": "integer",
            "export": true,
            "default": 3306,
            "readOnly": true
          },
        },
        "additionalProperties": false
      }, 
      "values": {}
    },
    "selectors": {
      "category": "Database",
      "imported": false,
      "provider": "AWS",
      "sub_category": "Relational Database"
    }
  }

  This example details how to create a specification for a MySQL service that is tailored to specific organizational and account settings, emphasizing visibility, reuse, and parameter specification.

  • Visibility

    • Organization: organization=12345:account=12345:namespace=28
    • This service is exclusively visible within the namespace 28 of the specified organization and account.

  • Attributes Specification Defined using JSON Schema, the attributes specify the essential connection details required by any application utilizing this service:

    • Host: The hostname or IP address where the MySQL database server is located.
    • Port: The port number on which the MySQL database server is listening.

  For further details, please refer to the Create Service Specification section in our API documentation for more detailed information

• Link Specification: Specifies who can use which service and under what conditions. It includes the specification of which service instance can be linked and under which dimensional conditions. Attributes of a link, like database schema, username, and password, are also defined using JSON Schema.

  Example MySQL Link Specification

  {
    "name": "Link MySQL Database",
    "unique": false,
    "attributes" : {
      "schema": {
        "type": "object",
        "required": ["username", "password", "name"],
        "properties": {
          "name": {
            "type": "string",
            "export": true,
            "readOnly": true
          },
          "password": {
            "type": "string",
            "export": {
              "type": "environment_variable",
              "secret": true
            },
            "readOnly": true
          },
          "username": {
            "type": "string",
            "export": true,
            "readOnly": true
          }
        },
        "additionalProperties": false
      }, 
      "values": {}
    },
    "specification_id": "afe74a12-0d28-4b41-8f25-8b58b2f09186"
  }

  In this example, we have specified a link for a MySQL service, including all necessary attributes: name, username, and password. Additionally, it is indicated whether these attributes should be exported as parameters within the service configuration. For further details, please refer to the Create Link Specification section in our API documentation for more detailed information

• Action Specification: Determines the actions that can be performed on services or links. This includes not only basic operations like creation, update, and deletion but also custom actions such as generating a temporary user and password for database access.

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.

Getting Started with Services

• Service Specification Process: Typically managed by the infrastructure team, this process involves defining which services will be provisioned and used. It details the visibility, attributes, restrictions, and lifecycle of these services. Before beginning, please ensure that:

  • You have reviewed our Service API Documentation to understand how to list and manage service links.
  • You are familiar with the principles and application of JSON Schema, which is used for defining service attributes.
    • You understand our additional JSON Schema keywords:

      • export: Specifies if an attribute should be exported as a parameter. The options include:

        • boolean: true or false. Attributes with true are exported as environment variables and treated as non-secret parameters.
        • object: This option allows more detailed specifications:
          • type: The parameter can be exported as an environment_variable or a file.
          • target: Specifies the name of the parameter, for example,MY_PARAMETER. Supports naming templates with injected service and link objects, allowing dynamic parameter names such as ${service.slug}_${link.slug} or ${service.slug}_MY_PARAMETER
          • secret: Indicates whether the parameter should be treated as a secret.

      • target: Indicates whether an action modifies an attribute of a link or service. For example, for the MySQL password attribute, a custom action could be defined to reset the password. In this case, the action's result attributes should specify password as the target.

      • config: Determines whether an attribute or action parameter retrieves its value from an NRN entry. The format for specifying this is as follows:

        • object:
          • key: The name of the NRN entry key. For example, aws.region.
          • nrn: The NRN identifier where the requested key is located. For example, organization=1:account=1.

      • exportIgnore: Specifies at the object level in a link specification attributes schema whether one or more service parameters should be ignored when exporting their values to parameters, for example, exportIgnore: 'my_attribute' or exportIgnore: ['my_attribute', 'another_attribute']

      • secret: Specifies if the attribute must be treated as secret ensuring that the value is not shown.

      • additionalKeywords: Specifies additional keywords to generate a dynamic schema with values from a service instance, link instance, application, or scopes. For example, if you want to choose roles from a list of available roles of the service:

        ...
        "roles": {
          "type": "array",
          "items": {
            "type": "string",
            "additionalKeywords": {
              "enum": ".service.attributes.availableRoles"
            }
          }
        }
        ...

        You can apply additionalKeywords to any JSON schema keyword you want to make dynamic, such as enum, default, minimum, maximum, etc.

        The value of each additionalKeywords entry must be a jq command-line filter applied to the provided context with the following structure:

        {
          "service": { ... },
          "link": { ... },
          "application":{ ... },
          "scopes": [{ ... }, { ... }],
        }

        Here are some practical examples of using additionalKeywords with different jq filters:

        {
          "additionalKeywords": {
            "enum": ".service.attributes.availableRoles",
            "enum": ". | [.scopes[]?.slug // \"You need to create an scope\"]",
            "default": ".application.metadata.my_metadata"
          }
        }

  Then you can use our API to create new service, links and actions definitions.

• Creation and Usage of Services: Usually performed by the development team, this involves creating new instances of a service based on the infrastructure team’s specifications and integrating these services into applications.

  • As a developer, navigate to the Services section. Here, you will find options to:

    • View Services: Browse existing application services.
    • Create New Services: Set up new services as per your requirements.
    • Link Existing Services: Establish connections between existing services and other components of your system.
    
    
    

  • To create new services:

    1. Click on the Create New Services option.
    2. Select the desired service specification from the list provided.
    3. Click the Create button to start the creation of your new service.
    
    
    
    
    4. Fill service form and click Create service
    
    
    
    
    5. Once service is created you can click Link to start using your service
    
    
    
    
    5. Fill link form and click Create link
    
    
    
    
    6. Finally you will se that a new service was created, linked
    
    
    
    
    

    and that a new parameter was created