Here's a typical workflow for starting rails console in production without Cased:

1. A developer looks up the bastion host IP
2. They configure their SSH key to gain access into the host
3. They look up on internal documentation to find the right EC2 instance
4. They SSH into the instance
5. They look up on internal documentation to find the right docker container
6. They enter the correct docker container prompt
7. They enter rails console

The workflow with Cased:

1. Developer logs in to Cased Shell using their identity provider
2. Developer clicks on the prompt they need access to
3. Developer enters rails console. Done.

By simply saving time on tedious, repetitive tasks per engineer per week - you're making your smaller team as effective as a larger team. Don't allow your developers to be blocked - expedite their workflows with Cased's automatic prompt discovery feature.

We'll walk through how Cased Shell can easily be configured to provide quick and easy access to the command-line prompts your team uses on a daily basis with our host and prompt auto-detection feature. Rails console, database shells, and any container prompt are now just one click away. No more searching for IP addresses or container hashes.

Overview

To get started, you'll need to setup Cased Jump. Cased Jump is an auto-discovery agent designed to run alongside of Cased Shell. It reads YAML files containing queries to run against compute providers, executes those queries against your cloud provider's APIs, and writes a JSON manifest containing the results of those queries. The manifest is updated every 30s as the agent runs. Cased Shell will read this manifest and display the results on the dashboard along with the included metadata, giving you one-click access to the tools your teems need.

P.S.: It's a best practice to use our Terraform-based ECS deployment to enable auto-prompt detection. You'll find more about this later in the "Configuring prompt auto-detection" section of the post.

Usage of Jump

./jump queries.yaml [queries2.yaml ...] results.json

Setting up Jump

Writing queries

Creating these queries require only one component, provider. The rest of the components are optional, allowing for organizations to customize Cased Shell to their liking.

Required components

• provider: The provider to query. ecs, ec2, and static are currently supported.

Optional components

• filters: A list of filters to apply to the query. Arguments vary by provider. (See the providers section for more information.)
• limit, sortOrder, and sortBy: Optional arguments to limit the results, sort the results, and sort the results by a particular field.
• prompt: Metadata to apply to all results returned by this query.
  • hostname: The hostname to SSH to when connecting to the prompt. Useful for injecting a jump host into the prompt if necessary.
  • ipAddress: The IP address to SSH to when connecting to the prompt. Overrides hostname.
  • port: The port to use when connecting to the prompt.
  • username: The username to use when establishing an SSH connection to the prompt.
  • name: A descriptive name for the prompt.
  • description: A longer description of the prompt.
  • jumpCommand: A command to execute immediately after connecting to the host over SSH. Example: docker exec -it app-container
  • shellCommand: A command to execute immediately after running jumpCommand. Example: ./bin/rails console
  • preDownloadCommand: A command to run before processing a user request to download a file. The tokens {filepath} and {filename} will be replaced with the full path and filename of the file to download. The command is expected to output the path to the file to download to stdout.
  • closeTerminalOnExit: A boolean indicating whether to close the terminal when the command or session initiated on the remote server exits. Defaults to true.
  • kind: The "kind" of prompt this is. Currently supported values are "container" and "host".
  • featured: Set to true to display this prompt above the fold on the Cased Shell Dashboard.
  • labels: A list of key/value pairs describing key characteristics of this prompt. The Cased Shell Dashboard will support filtering prompts by these labels.
  • annotations: A list of key/value pairs describing additional characteristics of this prompt. The Cased Shell Dashboard will NOT support filtering prompts by these labels, but may display them for additional context.
  • principals: A list of Principals that are known to be allowed to access this prompt. If present, the Cased Shell Dashboard will only display prompts to IDP users that are authorized one of these Principals, for example by membership in a group.
  • promptForKey: A boolean that indicates whether or not to prompt for an SSH key when connecting to the prompt.
  • promptForUsername: A boolean that indicates whether or not to prompt for a username when connecting to the prompt even if one is set as a default.

Supported cloud providers

Your infrastructure may include a frequently-changing collection of hosts. For this use case, Cased Shell includes a 'static' provider which allows statically configured hosts, or supports the dynamic listing of hosts using API calls against another provider. Currently, Cased Shell's prompt auto-detection feature discovers prompts by running queries against the EC2 and ECS APIs (AWS). Please contact us if you’d like to use Cased Shell to detect prompts on another provider!

ec2

Filters supported by the ec2 provider

• region: The AWS region to query. Defaults to the current region.

In addition to the above filter keys, the EC2 Provider also accepts all keys that are valid for ec2.DescribeInstanceInput.Filters, documentation on which is available at https://docs.aws.amazon.com/sdk-for-go/api/service/ec2/#DescribeInstancesInput.

Sorting

The EC2 Provider supports sorting by the following keys:

• launchTime

ecs

Filters supported by the ecs provider

• region: The AWS region to query. Defaults to the current region.
• cluster: The ECS cluster to query. Defaults to the 'default cluster'.
• task-group: The name of the ECS Task Group.
• container-name: The name of a running Container.

In addition to the above filter keys, the EC2 Provider also accepts all keys that are valid for ec2.DescribeInstanceInput.Filters, documentation on which is available at https://docs.aws.amazon.com/sdk-for-go/api/service/ec2/#DescribeInstancesInput.

Sorting

The ECS Provider supports sorting by the following keys:

• startedAt

static

The static provider is a simple provider that does not perform any queries. It is useful for including static prompts along with dynamic ones.

Simplest configuration

queries:
  - provider: ec2

Example configuration w/ optional variables

queries:
  # Include the most recently launched EC2 instance in the `us-west-2` region with an `aws:autoscaling:groupName` tag matching `*bastion*`
  - provider: ec2
    limit: 1
    sortBy: launchTime
    sortOrder: desc
    filters:
      region: us-west-2
      tag:aws:autoscaling:groupName: '*bastion*'
    prompt:
      labels:
        app: bastion
  # Include prompts for all EC2 instances in the `us-west-2` region with an `aws:autoscaling:groupName` tag matching `*prod-cluster*`, configured to proxy their SSH connections through a host in the bastion group above.
  - provider: ec2
    filters:
      region: us-west-2
      tag:aws:autoscaling:groupName: '*prod-cluster*'
    prompt:
      labels:
        cluster: test
      proxyJumpSelector:
        app: bastion
  # Include one featured prompt that allows engineers to connect to a Rails console on the most recently started app container in the production cluster.
  - provider: ecs
    filters:
      region: us-west-2
      cluster: prod-cluster
      container-name: app-container
    limit: 1
    sortBy: startedAt
    sortOrder: desc
    prompt:
      name: Production Rails Console
      description: Use to perform exploratory debugging on the production cluster
      shellCommand: ./bin/rails console
      labels:
        environment: prod
      proxyJumpSelector:
        app: bastion
# Use the static provider to include an additional statically defined prompt.
  - provider: static
    prompt:
      featured: true
      hostname: example.com
      username: example

Configuring prompt auto-detection

When using our supported Terraform-based ECS deployment, Cased Shell’s prompt auto-detection feature is enabled by providing a list of jump_queries to the Terraform module. Each query has three general parts: provider configuration, filters, and prompt metadata:

jump_queries = [
  {
    # Provider configuration
    provider  = "ec2"        # ec2, ec2, or static
    limit     = 1            # optional, defaults to no limit
    sortOrder = "desc"       # optional, defaults to "asc"
    sortBy    = "startedAt"  # optional, provider specific

    # Filters
    # See https://github.com/cased/jump#providers for a full list of filters for each provider.
    filters   = {
        "tag:aws:autoscaling:groupName" = "*test*"
    }

    # Prompt metadata can be used to customize how this prompt is displayed,
    # as well as influence how Cased Shell connects to this prompt.
    prompt   = {
      name        = "Newest test instance" 
      description = "The newest instance in the 'test' autoscaling group."

      # Prompts can be "featured" above the fold by setting this value to true.
      featured    = true

      # Labels can be used to filter and group related prompts together.
      labels      = {
        environment = "test"
      }

      # If necessary, the SSH connection established when clicking on this prompt
      # can be configured using the following fields:
      # hostname = "example.com"
      # ipAddress = "1.2.3.4"
      # port      = "2222"
      # username  = "root"

      # If this prompt requires a key or username different from the default,
      # you can set the following fields to prompt the user each time:
      # promptForUsername = true
      # promptForKey      = true

      # Additional commands can be run immedaitely after connecting to a
      # prompt by setting the following fields:
      # jumpCommand  = "docker exec -it app-container"
      # shellCommand = "./bin/rails console"

      # If the instance that this prompt points has restricted access to 
      # its SSH ports to instances in another security group, you can instruct
      # Cased Shell to automatically proxy the connection via _another_ prompt
      # it knows about by using the `proxyJumpSelector` field, which expects a
      # hash of labels that identify the prompt to proxy the connection through.

      # proxyJumpSelector = {
      #   app = "bastion"
      # }

    }
  }
]

Example configuration

jump_queries = [
    # The most recently launched bastion instance in the test cluster
    {
      provider = "ec2"
      filters = {
        "tag:aws:autoscaling:groupName" = "*bastion*"
        "tag:cluster"                   = "*test*"
      }
      limit     = 1
      sortBy    = "launchTime"
      sortOrder = "desc"
      prompt = {
        name        = "Bastion host"
        featured    = true
        description = "newest bastion instance"
        labels = {
          environment = "test"
          app         = "bastion"
          shell       = "bash"
        }
      }
    },
    # All EC2 nodes in the test ECS cluster, proxied through the bastion host
    # above.
    {
      provider = "ec2"
      filters = {
        "tag:aws:autoscaling:groupName" = "*test*"
      }
      prompt = {
        name = "ECS node"
        labels = {
          environment = "test"
          app         = "ecs"
          shell       = "bash"
        }
        proxyJumpSelector = {
          app = "bastion"
        }

      }
    },
    # A Rails console in the container called "rails" launched as a part of the
    # "test-service"  ECS service in the test ECS cluster, proxied through the
    # bastion host above. This prompt is featured to provide one click access
    # to the Rails console.
    {
      provider = "ecs"
      filters = {
        cluster        = "test"
        task-group     = "service:test-service"
        container-name = "rails"
      }
      limit     = 1
      sortBy    = "startedAt"
      sortOrder = "desc"
      prompt = {
        name         = "Rails Console"
        featured     = true
        description  = "Use to perform exploratory debugging on the test cluster"
        shellCommand = "./bin/rails console"
        labels = {
          environment = "test"
          app         = "rails"
          shell       = "rails"
        }
        proxyJumpSelector = {
          app = "bastion"
        }
      }
    },
    # Allow access to a bash prompt on all Rails containers on the test cluster.
    {
      provider = "ecs"
      filters = {
        cluster        = "test"
        task-group     = "service:test-service"
        container-name = "rails"
      }
      prompt = {
        name         = "Bash on rails container"
        shellCommand = "/bin/bash"
        labels = {
          environment = "test"
          app         = "rails"
          shell       = "bash"
        }
        proxyJumpSelector = {
          app = "bastion"
        }
      }
    }
  ]

And just like that, you now have host and container auto-detection enabled on Cased Shell. Your team is now enabled to quickly access the command-line tools they need - whether they exist on a long-lived host, or on a container created 45 seconds ago.

If you're interested and want to learn more about Cased Shell, feel free to schedule a demo, read the documentation, or send us an email at team@cased.com.