Defining endpoints

Components of any type can specify the endpoints that the container exposes. These endpoints can be made accessible to the users if the Devfile cluster is running using a Kubernetes ingress or an OpenShift route and to the other components within the workspace. You can create an endpoint for your application or database, if your application or database server is listening on a port and you want to be able to directly interact with it yourself or you want other components to interact with it.

Procedure

  1. Specify endpoints properties as shown in the following example:

    Example 1. Specify endpoints properties
    schemaVersion: 2.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    git:
      remotes:
        origin: "https://github.com/acme/my-go-project.git"
components:
  - name: go
    container:
      image: golang
      memoryLimit: 512Mi
      mountSources: true
      command: ['sleep', 'infinity']
      env:
        - name: GOPATH
          value: $(PROJECTS_ROOT)/go
        - name: GOCACHE
          value: /tmp/go-cache
      endpoints:
      - name: web
        targetPort: 8080
        configuration:
          discoverable: false
          public: true
          protocol: tcp
          scheme: http
  - name: postgres
    container:
      image: postgres
      memoryLimit: 512Mi
      env:
        - name: POSTGRES_USER
          value: user
        - name: POSTGRES_PASSWORD
          value: password
        - name: POSTGRES_DB
          value: database
      endpoints:
        - name: postgres
          targetPort: 5432
          configuration:
            discoverable: true
            public: false

Here, there are two container, each defining a single endpoint. Endpoint is an accessible port that can be made accessible inside the workspace or publicly (example, from the UI). Each endpoint has a name and port, which is the port on which certain server running inside the container is listening. The following are a few attributes that you can set on the endpoint:

  • discoverable: If an endpoint is discoverable, it means that it can be accessed using its name as the host name within the workspace containers (in the Kubernetes parlance, a Service is created for it with the provided name).

  • public: The endpoint will also be accessible outside of the workspace: such endpoint can be accessed from the Devfile user interface and is always exposed on port 80 or 443 (depending on whether tls is enabled in Devfile).

  • protocol: For public endpoints the protocol is a hint to the UI on how to construct the URL for the endpoint access. Typical values are http, https, ws, wss.

  • secure: A boolean (defaulting to false) specifying whether the endpoint is put behind a JWT proxy requiring a JWT workspace token to grant access. The JWT proxy is deployed in the same Pod as the server and assumes the server listens solely on the local loopback interface, such as 127.0.0.1.

    Listening on any other interface than the local loopback poses a security risk because such server is accessible without the JWT authentication within the cluster network on the corresponding IP addresses.

  • path: The URL of the endpoint.

  • unsecuredPaths: A comma-separated list of endpoint paths that are to stay unsecured even if the secure attribute is set to true.

  • cookiesAuthEnabled: When set to true (the default is false), the JWT workspace token is automatically fetched and included in a workspace-specific cookie to allow requests to pass through the JWT proxy.

    This setting potentially allows a CSRF attack when used in conjunction with a server using POST requests.

When starting a new server within a component, Devfile autodetects this, and the UI offers to automatically expose this port as a public port. This is useful for debugging a web application, for example. It is impossible to do this for servers that autostart with the container (for example, a database server). For such components, specify the endpoints explicitly.

Example specifying endpoints for kubernetes/openshift and plugin types:

schemaVersion: 2.0.0
metadata:
  name: MyDevfile
components:
  - name: theia-editor
    plugin:
      id: eclipse/che-theia/next
      endpoints:
      - name: 'theia-extra-endpoint'
        targetPort: 8880
        configuration:
          discoverable: true
          public: true

  - plugin:
      id: redhat/php/latest
      memoryLimit: 1Gi
      endpoints:
      - name: 'php-endpoint'
        targetPort: 7777

  - plugin:
      name: theia-editor
      id: eclipse/che-theia/next
      endpoints:
      - name: 'theia-extra-endpoint'
        targetPort: 8880
        configuration:
          discoverable: true
          public: true

  - openshift:
      name: webapp
      reference: webapp.yaml
      endpoints:
      - name: 'web'
        targetPort: 8080
        configuration:
          discoverable: false
          public: true
          protocol: http

  - openshift:
      name: mongo
      reference: mongo-db.yaml
      endpoints:
      - name: 'mongo-db'
        targetPort: 27017
        configuration:
          discoverable: true
          public: false