Creating Concourse Instances

IMPORTANT: The Concourse for PCF tile is currently in Beta and is meant for evaluation and test purposes only. Do not use this product in a PCF production environment.

This topic explains how developers can create Concourse service instances in Pivotal Cloud Foundry (PCF) and target those instances with the Fly CLI. This topic also provides resources for getting started with pipeline creation.

Create a Concourse Service Instance

  1. Log in to the Cloud Foundry Command Line Interface (cf CLI):

    $ cf login -u USERNAME -p PASSWORD
    

  2. Download and install the Concourse for PCF CLI plugin:

    1. Navigate to Pivotal Network and download the correct takeoff-cf-plugin file for your operating system.
    2. Run the following commands:
      $ chmod +x ~/Downloads/takeoff-0.0.2.cf-plugin-MY-OPERATING-SYSTEM
      $ cf install-plugin ~/Downloads/takeoff-0.0.2.cf-plugin-MY-OPERATING-SYSTEM
      
  3. Target the org and space where you want to create a service instance:

    $ cf target -o MY-ORG -s MY-SPACE
    

  4. Create a Concourse instance:

    $ cf create-service-concourse PLAN-NAME INSTANCE-NAME -w NUMBER-OF-INSTANCES
    

    • Plan name: Operators define plans in the Concourse tile in Ops Manager. You can contact your operator or check Apps Manager for available plans.
    • Instance name: Enter a name for your service instance.
    • Number of instances: Specify a number of instances. This defaults to what the operator specified as the minimum when configuring the plan in the Concourse tile.
    • Optional Github Authentication Flags: Use any of the following to allow users of your instance to authenticate with Github in addition to UAA.
      Flag Description
      --github-auth-organization=ORG Replace ORG with the Github org that can access this service instance.
      --github-auth-team=ORG/TEAM Replace ORG/TEAM with the Github org and team than can access this service instance.

      Note: The team name is case-sensitive and must exactly match the team name in Github.

      --github-auth-user=LOGIN Replace LOGIN with the Github user that can access this service instance.
  5. Run the following command to see the details and status of the instance you created. It may take a few minutes before the command returns Status: create succeeded.

    $ cf service INSTANCE-NAME
    Service instance: INSTANCE-NAME
    Service: concourse
    Tags:
    Plan: MY-PLAN
    Description: Concourse as a Service
    Documentation url: https://docs.pivotal.io/p-concourse
    Dashboard: https://p-concourse.MY-SYSTEM-DOMAIN/teams/MY-ORG-MY-SPACE-INSTANCE-NAME-UID/login
    
    Last Operation Status: create succeeded Message: Instance provisioning completed Started: 2016-09-07T18:15:49Z Updated: 2016-09-07T18:19:56Z

Target your Instance with the Fly CLI

  1. Download the Concourse Fly CLI tool at https://p-concourse.YOUR-SYSTEM-DOMAIN.

  2. If you want to log in as an admin, obtain the admin credentials:

    1. From Ops Manager, click the Concourse tile.
    2. Select the Credentials tab.
    3. Under the Concourse job, in the Web Credentials row, click Link to Credential.
    4. Record the username and password.
  3. Log in to Fly:

    $ fly -t TARGET-NAME login -c https://p-concourse.YOUR-SYSTEM-DOMAIN \
    -n YOUR-TEAM-NAME --ca-cert=./YOUR-ROOT-CA.crt
    
    navigate to the following URL in your browser: https://p-concourse.YOUR-SYSTEM-DOMAIN/auth/uaa?team_name=YOUR-TEAM-NAME

    • Target name: Choose a target name to be the alias for the service instance you created. See the Authenticating with and Saving Concourse targets topic for more information.
    • Team name: This value appears in the output of cf service INSTANCE-NAME, in the Dashboard URL, after teams/. For example, in the dashboard URL https://p-concourse.example.com/teams/system-space1-user4-636c/login, the team name is system-space1-user4-636c. The format of the team name is: org name + space name + service instance name + 4 digit #. The Concourse service constructs the name string this way to avoid name collisions. See the Concourse documentation to learn more about teams.
    • CA certificate: Ask your operator for the root CA certificate of your deployment.
  4. When you log in and target for the first time, the Fly CLI provides you with a URL. Point your browser to the dashboard URL provided by Fly in the previous step.

    1. Log in using your UAA credentials.

      Note: If you see 401 Not Authorized, contact your PCF administrator and ensure that you have the SpaceDeveloper role in the PCF org and space where the instance was created.

  5. You can now run Fly commands against your instance. See the following examples:

    • To list your pipelines:
      $ fly -t TARGET-NAME pipelines
      name  paused  public
      
    • To list your workers:
      $ fly -t TARGET-NAME workers
      name                                  containers  platform  tags  team
      268b9d7c-1666-4878-8821-c20f3a2cd075  0           linux     none  system-space3-team-user4-636c
      
      See the Fly CLI topic of the Concourse documentation for a full list of Fly commands.

Set up Pipelines

Now that you have a Concourse instance, you can build CI pipelines. See the Using Concourse documentation to get started with Concourse. The documentation includes tutorials, explanations of Concourse concepts such as pipelines and build plans.

If you are new to Concourse the Flight School tutorial is a good place to start.

Create a pull request or raise an issue on the source for this page in GitHub