trek

README

Trek

Trek is a CLI/ncurses explorer for HashiCorp Nomad clusters.

SETUP

Binary Release

Get to revisions, and download a binary.

From Source

git clone https://github.com/franckverrot/trek.git
cd trek
make trek

USAGE

TL;DR Start ./trek -help to get the usage prompt.

CLI

The CLI can be used without a UI. This allows scripting to access IP, ports, and other info exposed by Nomad.

Options

Here's a list of options available:

• nomad-address: address of the nomad cluster

• list-jobs: list jobs running on the cluster

λ ./trek -list-jobs
* example
* example34

NOTE : this option also works in conjunction with display-format

• job: select a specific job

λ trek -job example34
* cache34
* cache56

• task-group: select a specific task group

λ trek -job example34 -task-group cache56
* example34.cache56[0]

• allocation: select a specific allocation number

λ trek -job example34 -task-group cache56 -allocation 0
(0) redis5
(1) redis6

• task-name: select a specific task name

λ trek -job example34 -task-group cache56 -allocation 0 -task-name redis6
* Name: redis6
* Node Name: feynman.local
* Node IP: 127.0.0.1
* Driver: docker
        * image: redis:3.2
        * port_map: [map[db:6379]]
* Dynamic Ports: 24832 (db)

• display-format: Use the Go templating language to format output when describing a specific job, task group, allocation or task
  • Context-specific data made available:
    • Job
      • TaskGroups (array of task groups): task groups part of the job definition
    • Task Group
      • Allocations (array of allocations): allocations run by that task group
    • Allocation
      • IP (string): node onto which we're running the selected allocation
      • Tasks (array of tasks): tasks being run by that allocation
    • Task
      • IP (string): node onto which we're running the selected task
      • Network: network information (like ports)
      • Environment: environment variables provided to the task
  • Available functions:
    • {{Debug <x>}} : show raw representation of the data <x>
    • {{DebugAll}} : show raw representation of everything provided to the template
  • Examples:

λ trek -job example34 -task-group cache56 -allocation 0 -task-name redis6 -display-format "{{DebugAll}}"
DEBUG ALL: {IP:127.0.0.1 Network:{Ports:map[db:{Value:23109 Reserved:false}]} Environment:map[FOO_BAR:{Value:baz_bat}]}

λ trek -job example34 -task-group cache56 -allocation 0 -task-name redis6 -display-format "{{Debug .Environment}}"
DEBUG: map[FOO_BAR:{Value:baz_bat}]

λ trek -job example34 -task-group cache56 -allocation 0 -task redis6 -display-format "{{range .Network.Ports}}{{$.IP}}:{{.Value}}{{println}}{{end}}"
127.0.0.1:31478
127.0.0.1:25142

ncurses UI

./trek -ui=true

Trek Configuration File

Example

{ "Environments" : [ { "Name" : "development" , "Address" : "http://127.0.0.1:4646" }
                   ]
}

Options

• Environments: List of environments (given a name and address) Trek can connect to

FAQ

• How do I ssh into an allocation's node?

  λ ssh $(trek -job ... -task-group ... -allocation 0 -display-format "{{.IP}}")

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit.
• Send me a pull request. Bonus points for topic branches.

Copyright

Copyright (c) 2019 Franck Verrot. MIT LICENSE. See LICENSE for details.