> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create load balancer

> Create a new load balancer.



## OpenAPI

````yaml /openapi/region-openapi.yaml post /api/v2/loadbalancers
openapi: 3.0.3
info:
  title: Region Service API
  description: >-
    Cloud region discovery and routing service.  This is service not intended
    for direct access

    by end users.  Region related functionality is typically exposed by higher
    level services

    e.g. Compute and Kubernetes, that provide subsets of resources that are
    compatible with

    that service.
  version: 1.13.0
servers: []
security: []
paths:
  /api/v2/loadbalancers:
    description: Manages network scoped layer 4 load balancers.
    post:
      tags:
        - Load balancers
      summary: Create load balancer
      description: Create a new load balancer.
      requestBody:
        $ref: '#/components/requestBodies/loadBalancerV2CreateRequest'
      responses:
        '201':
          $ref: '#/components/responses/loadBalancerV2Response'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '422':
          $ref: '#/components/responses/unprocessableContentResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      security:
        - oauth2Authentication: []
components:
  requestBodies:
    loadBalancerV2CreateRequest:
      description: A request for a load balancer.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/loadBalancerV2Create'
          example:
            metadata:
              name: web-lb
              description: Public TCP load balancer
              tags:
                - name: service
                  value: ingress
            spec:
              networkId: 61f0ad85-3001-41cb-824a-e6a047668dfe
              publicIP: true
              vipAddress: 192.168.10.20
              listeners:
                - name: http
                  protocol: tcp
                  port: 80
                  allowedCidrs:
                    - 0.0.0.0/0
                  idleTimeoutSeconds: 30
                  pool:
                    proxyProtocolV2: false
                    members:
                      - address: 10.0.0.10
                        port: 8080
                    healthCheck:
                      intervalSeconds: 10
                      timeoutSeconds: 5
                      healthyThreshold: 2
                      unhealthyThreshold: 2
  responses:
    loadBalancerV2Response:
      description: A load balancer.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/loadBalancerV2Read'
          example:
            metadata:
              id: a64f9269-36e0-4312-b8d1-52d93d569b7b
              name: web-lb
              organizationId: 9a8c6370-4065-4d4a-9da0-7678df40cd9d
              projectId: e36c058a-8eba-4f5b-91f4-f6ffb983795c
              creationTime: '2024-05-31T14:11:00Z'
              createdBy: john.doe@acme.com
              provisioningStatus: pending
              healthStatus: healthy
            spec:
              publicIP: true
              listeners:
                - name: http
                  protocol: tcp
                  port: 80
                  allowedCidrs:
                    - 0.0.0.0/0
                  idleTimeoutSeconds: 30
                  pool:
                    proxyProtocolV2: false
                    members:
                      - address: 10.0.0.10
                        port: 8080
                    healthCheck:
                      intervalSeconds: 10
                      timeoutSeconds: 5
                      healthyThreshold: 2
                      unhealthyThreshold: 2
            status:
              regionId: d891dbf0-0a01-4efc-ae3a-5d77f6d3424b
              networkId: 61f0ad85-3001-41cb-824a-e6a047668dfe
              vipAddress: 192.168.10.20
              publicIP: 203.0.113.10
    badRequestResponse:
      description: |-
        Request body failed schema validation, or the request does not contain
        all the required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: invalid_request
            error_description: request body invalid
            trace_id: 57bc14d9bd461f0b5a72db830149b67a
    unauthorizedResponse:
      description: Authentication failed or the access token has expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: access_denied
            error_description: authentication failed
            trace_id: 57bc14d9bd461f0b5a72db830149b67a
    forbiddenResponse:
      description: >-
        Request was denied by authorization, this may be caused by the
        authorization

        token not having the required scope for an API, or the user doesn't have
        the

        necessary privileges on the provider platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: forbidden
            error_description: user credentials do not have the required privileges
            trace_id: 57bc14d9bd461f0b5a72db830149b67a
    notFoundResponse:
      description: Unable to find a resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: not_found
            error_description: the requested resource does not exist
            trace_id: 57bc14d9bd461f0b5a72db830149b67a
    unprocessableContentResponse:
      description: >-
        The provided request was syntactically correct but the instruction was
        unable to

        be processed due to semantic errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: unprocessable_content
            error_description: the request body was in the wrong format
            trace_id: 57bc14d9bd461f0b5a72db830149b67a
    internalServerErrorResponse:
      description: >-
        An unexpected or unhandled error occurred. This may be a transient error
        and

        may succeed on a retry.  If this isn't the case, please report it as an
        issue.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: server_error
            error_description: failed to token claim
            trace_id: 57bc14d9bd461f0b5a72db830149b67a
  schemas:
    loadBalancerV2Create:
      description: A load balancer creation request.
      type: object
      required:
        - metadata
        - spec
      properties:
        metadata:
          $ref: '#/components/schemas/resourceMetadata'
        spec:
          $ref: '#/components/schemas/loadBalancerV2CreateSpec'
    loadBalancerV2Read:
      description: A load balancer.
      type: object
      required:
        - metadata
        - spec
        - status
      properties:
        metadata:
          $ref: '#/components/schemas/projectScopedResourceReadMetadata'
        spec:
          $ref: '#/components/schemas/loadBalancerV2Spec'
        status:
          $ref: '#/components/schemas/loadBalancerV2Status'
    error:
      description: Generic error message, compatible with oauth2.
      type: object
      required:
        - error
        - error_description
      properties:
        error:
          description: >-
            A terse error string expanding on the HTTP error code. Errors are
            based on the OAuth 2.02 specification, but are expanded with
            proprietary status codes for APIs other than those specified by
            OAuth 2.02.
          type: string
          enum:
            - invalid_request
            - server_error
            - access_denied
            - not_found
            - conflict
            - method_not_allowed
            - unsupported_media_type
            - request_entity_too_large
            - unprocessable_content
            - forbidden
        error_description:
          description: Verbose message describing the error.
          type: string
        trace_id:
          description: Unique trace identifier for the request.
          type: string
    resourceMetadata:
      description: Metadata required for all API resource reads and writes.
      required:
        - name
      properties:
        name:
          $ref: '#/components/schemas/kubernetesLabelValue'
        description:
          description: >-
            The resource description, this optionally augments the name with
            more context.
          type: string
        tags:
          $ref: '#/components/schemas/tagList'
    loadBalancerV2CreateSpec:
      description: A load balancer creation specification.
      type: object
      allOf:
        - $ref: '#/components/schemas/loadBalancerV2Spec'
        - type: object
          required:
            - networkId
          properties:
            networkId:
              $ref: '#/components/schemas/networkId'
            vipAddress:
              $ref: '#/components/schemas/ipv4Address'
              description: >-
                The requested virtual IP address. When provided, it must fall
                within the selected network CIDR.
    projectScopedResourceReadMetadata:
      description: Metadata required by project scoped resource reads.
      allOf:
        - $ref: '#/components/schemas/organizationScopedResourceReadMetadata'
        - type: object
          required:
            - projectId
          properties:
            projectId:
              description: The project identifier the resource belongs to.
              type: string
    loadBalancerV2Spec:
      description: A load balancer's specification.
      type: object
      required:
        - listeners
      properties:
        publicIP:
          description: Whether to allocate a public IP.
          type: boolean
        listeners:
          description: A list of load balancer listeners.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/loadBalancerListenerV2'
    loadBalancerV2Status:
      description: Read only status information about a load balancer.
      type: object
      required:
        - regionId
        - networkId
      properties:
        regionId:
          description: The region the load balancer belongs to.
          type: string
        networkId:
          description: The network the load balancer belongs to.
          type: string
        vipAddress:
          $ref: '#/components/schemas/ipv4Address'
          description: The provisioned virtual IP address.
        publicIP:
          $ref: '#/components/schemas/ipv4Address'
          description: The provisioned public IP address.
    kubernetesLabelValue:
      description: >-
        A valid Kubernetes label value, typically used for resource names that
        can be

        indexed in the database.
      type: string
      pattern: ^[0-9A-Za-z](?:[0-9A-Za-z-_.]{0,61}[0-9A-Za-z])?$
    tagList:
      description: A list of tags.
      type: array
      items:
        $ref: '#/components/schemas/tag'
    networkId:
      description: A network ID.
      type: string
      format: uuid
      x-go-type: regionids.NetworkID
      x-go-type-import:
        name: regionids
        path: github.com/unikorn-cloud/region/pkg/ids
    ipv4Address:
      description: An IPv4 address.
      type: string
      format: ipv4
    organizationScopedResourceReadMetadata:
      description: Metadata required by organization scoped resource reads.
      allOf:
        - $ref: '#/components/schemas/resourceReadMetadata'
        - type: object
          required:
            - organizationId
          properties:
            organizationId:
              description: The organization identifier the resource belongs to.
              type: string
    loadBalancerListenerV2:
      description: A load balancer listener.
      type: object
      required:
        - name
        - protocol
        - port
        - pool
      properties:
        name:
          $ref: '#/components/schemas/loadBalancerListenerNameV2'
          description: The listener name.
        protocol:
          $ref: '#/components/schemas/loadBalancerListenerProtocolV2'
        port:
          description: The listener port.
          type: integer
          minimum: 1
          maximum: 65535
        allowedCidrs:
          description: A list of source IPv4 CIDRs allowed to access the listener.
          type: array
          items:
            type: string
            pattern: >-
              ^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\/(?:3[0-2]|[1-2]?[0-9])$
        idleTimeoutSeconds:
          description: >-
            The idle timeout in seconds. Defaults to 60 for TCP listeners and is
            unsupported for UDP listeners.
          type: integer
          minimum: 1
          maximum: 86400
        pool:
          $ref: '#/components/schemas/loadBalancerPoolV2'
    tag:
      description: >-
        A tag mapping arbitrary names to values.  These have no special meaning

        for any component are are intended for use by end users to add
        additional

        context to a resource, for example to categorize it.
      type: object
      required:
        - name
        - value
      properties:
        name:
          description: A unique tag name.
          type: string
        value:
          description: The value of the tag.
          type: string
    resourceReadMetadata:
      description: Metadata required by all resource reads.
      allOf:
        - $ref: '#/components/schemas/staticResourceMetadata'
        - type: object
          required:
            - provisioningStatus
            - healthStatus
          properties:
            deletionTime:
              description: The time the resource was deleted.
              type: string
              format: date-time
            provisioningStatus:
              $ref: '#/components/schemas/resourceProvisioningStatus'
            healthStatus:
              $ref: '#/components/schemas/resourceHealthStatus'
    loadBalancerListenerNameV2:
      description: >-
        A load balancer listener name. Must start with a lower-case letter and
        otherwise be a valid DNS label.
      type: string
      maxLength: 63
      pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$
    loadBalancerListenerProtocolV2:
      description: The load balancer listener protocol.
      type: string
      enum:
        - tcp
        - udp
    loadBalancerPoolV2:
      description: A load balancer listener pool.
      type: object
      required:
        - members
      properties:
        proxyProtocolV2:
          description: Whether to enable Proxy Protocol v2.
          type: boolean
        members:
          description: A list of pool members.
          type: array
          items:
            $ref: '#/components/schemas/loadBalancerMemberV2'
        healthCheck:
          $ref: '#/components/schemas/loadBalancerHealthCheckV2'
    staticResourceMetadata:
      description: |
        This metadata is for resources that just exist, and don't require
        any provisioning and health status, but benefit from a standardized
        metadata format.
      type: object
      allOf:
        - $ref: '#/components/schemas/resourceMetadata'
        - type: object
          required:
            - id
            - creationTime
          properties:
            id:
              description: The unique resource ID.
              type: string
            creationTime:
              description: The time the resource was created.
              type: string
              format: date-time
            createdBy:
              description: The user who created the resource.
              type: string
            modifiedTime:
              description: The time a resource was updated.
              type: string
              format: date-time
            modifiedBy:
              description: The user who updated the resource.
              type: string
    resourceProvisioningStatus:
      description: The provisioning state of a resource.
      type: string
      enum:
        - unknown
        - pending
        - provisioning
        - provisioned
        - deprovisioning
        - error
    resourceHealthStatus:
      description: The health state of a resource.
      type: string
      enum:
        - unknown
        - healthy
        - degraded
        - error
    loadBalancerMemberV2:
      description: A load balancer pool member.
      type: object
      required:
        - address
        - port
      properties:
        address:
          $ref: '#/components/schemas/ipv4Address'
        port:
          type: integer
          minimum: 1
          maximum: 65535
    loadBalancerHealthCheckV2:
      description: A load balancer pool health check.
      type: object
      properties:
        intervalSeconds:
          type: integer
          minimum: 1
          maximum: 300
        timeoutSeconds:
          type: integer
          minimum: 1
          maximum: 300
        healthyThreshold:
          type: integer
          minimum: 1
          maximum: 10
        unhealthyThreshold:
          type: integer
          minimum: 1
          maximum: 10
  securitySchemes:
    oauth2Authentication:
      description: Operation requires OAuth 2.0 bearer token authentication.
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://identity.nks.europe-west4.nscale.com/oauth2/v2/authorization
          tokenUrl: https://identity.nks.europe-west4.nscale.com/oauth2/v2/token
          scopes: {}

````