App Token Tutorial

This tutorial demonstrates how to use an App Token to automate workload deployment using APC. See also the api-manifest-example sample application.

You can also use app tokens without APC if you want to make direct API calls to the cluster. For example, api-docker-example is a Node app that uses app tokens to make API calls to create an app from a Docker image.

Instructions

  1. Log in to your cluster as an admin user.

  2. Author policy to issue an access token to a capsule job (that you will create later).

     on job::/sandbox/admin::mycaptoken {
         { permit issue } 
         { tokenTimeout "3600s" }
     }
    

    screenshot

  3. Assign permissions to the job so that it's able to manage cluster resources. Just like a user, you need to grant resource permissions to the job using policy. The easiest way to do this is add the job's FQN to the default adminUsers policy document:

    1. Open the Web Console and click Policy.
    2. Open the adminUsers policy document and click Edit.
    3. To make the job a cluster admin, add the following rule to each realm in the document:

       if (auth_server@apcera.me->name == "job::/sandbox/admin::mycaptoken") { role admin }
      

      For example:

      screenshot

    4. Click Apply Changes when you are done.
  4. Create a Linux capsule and allow egress.

    Create a capsule using the same job name and namespace you specified in policy.

    Using APC:

     apc capsule create mycaptoken -i linux -ae
    

    Using the web console:

    screenshot

    screenshot

    screenshot

  5. Bind the job to the HTTP service.

    Binding the job to the HTTP service attaches an HTTP semantic pipeline to the job that will broker the connection.

    Using APC:

     apc service bind /apcera::http --job mycaptoken
    

    Using web console:

    screenshot

    The result is two jobs: the capsule and the attached HTTP semantic pipeline:

     apc job list
     Working in "/sandbox/admin"
     ╭──────────────────────────┬──────┬────────────────┬─────────┬───────────╮
     │ Name                     │ Type │ Namespace      │ Status  │ Instances │
     ├──────────────────────────┼──────┼────────────────┼─────────┼───────────┤
     │ mycaptoken               │ job  │ /sandbox/admin │ started │ 1/1       │
     │ mycaptoken/http/f58dbc88 │ job  │ /sandbox/admin │ started │ 1/1       │
     ╰──────────────────────────┴──────┴────────────────┴─────────┴───────────╯
    
  6. Connect to the capsule using APC:

     apc capsule connect mycaptoken
     -bash-4.3# 
    

    Note: The remainder of this tutorial explains how to use APC and app token together. However, it's worth noting you can also make API calls directly from the capsule without APC. For example, if your cluster is located at cluster-name.example.com, the following cURL command will list all services that the job's app token permits:

     bash-4.3# curl cluster-name.example.com/v1/services
     [{"uuid":"9cd9c1ed-2dcb-4340-99c0-3fd8a88e5eb9","fqn":"service::/sandbox/admin::my_generic_redis", ...}]
    
  7. Run the following commands to install APC on the capsule job, replacing <subdomain>.<domain>.<tld> with your cluster's information:

     wget http://api.<subdomain>.<domain>.<tld>/v1/apc/download/linux_amd64/apc.zip
     unzip apc.zip
     rm apc.zip
    

    For example:

     wget http://api.my-cluster.apcera-platform.io/v1/apc/download/linux_amd64/apc.zip
     unzip apc.zip
     rm apc.zip
    
  8. Set APC_HOME to a modifiable directory.

    The .apc file must be modifiable. The easiest way to do this is to set the APC_HOME environment variable to the current directory that the job runs in (root on the container).

    For example: APC_HOME='pwd'.

    This sets APC_HOME to the output of the pwd command (print working directory).

  9. Target your cluster using HTTP.

    Issue command apc target http://CLUSTER-NAME to target your cluster.

    For example: ./apc target http://my-cluster.apcera-platform.io

    Note: App token does not currently work with APC calls made over HTTPS.

  10. Log in to your cluster.

    Issue ./apc login --app-auth to login to your cluster using the appauth authentication type.

    This authentication type can only be used inside the cluster and is not valid if used without an application token being assigned in the HTTP semantic pipeline. To do this you must have policy in place as described earlier in this tutorial.

  11. To verify that you can make API calls using APC from within the capsule, create a new capsule from the capsule:

    ./apc capsule create mycap2 -i linux -ae
    

    If you receive a policy error such as the following, it means you did not grant the necessary permissions to the job (see step #3 above):

    Error: Not allowed to read "package::/apcera/pkg/os::ubuntu-14.04-apc3" by policy: missing claim "permit read" on "package::/apcera/pkg/os::ubuntu-14.04-apc3"