Merge branch '22864-kubernetes-deploy-with-terminal' into 'master'

Add online terminal support for Kubernetes

## What does this MR do?

Gives terminal access to kubernetes-deployed environments  via the deployment service

## Are there points in the code the reviewer needs to double check?

## Why was this MR needed?

Part of idea to production

## Screenshots (if relevant)

### `/root/reviewing/environments`

![Screen_Shot_2016-12-15_at_19.10.40](/uploads/bd2c54c07b6c85dec3328a20cd185b64/Screen_Shot_2016-12-15_at_19.10.40.png)

### `/root/reviewing/environments/10013`

![Screen_Shot_2016-12-19_at_12.52.39](/uploads/db4e4e06cda88437e8727433d65898b9/Screen_Shot_2016-12-19_at_12.52.39.png)

### `/root/reviewing/enviroments/10013/terminal`

![Screen_Shot_2016-12-15_at_02.35.52](/uploads/1bb77b7e2de2c657ae3bda62dc4f0970/Screen_Shot_2016-12-15_at_02.35.52.png)

## Does this MR meet the acceptance criteria?

- [x] [Changelog entry](https://docs.gitlab.com/ce/development/changelog.html) added
- [x] [Documentation created/updated](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/doc_styleguide.md)
- Tests
  - [X] Added for this feature/bug
  - [x] All builds are passing
- [X] Conform by the [merge request performance guides](http://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html)
- [X] Conform by the [style guides](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#style-guides)
- [x] Branch has no merge conflicts with `master` (if it does - rebase it please)
- [x] [Squashed related commits together](https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits)

## What are the relevant issue numbers?

* Closes #22864 #22958
* Alternative to, and somewhat based on,  !6770 
* Depends on https://gitlab.com/gitlab-org/gitlab-workhorse/merge_requests/83

See merge request !7690

app/assets/javascripts/environments/components/environment.js.es6

@@ -18,7 +18,7 @@
    * The environments array is a recursive tree structure and we need to filter
    * both root level environments and children environments.
    *
-   * In order to acomplish that, both `filterState` and `filterEnvironmnetsByState`
+   * In order to acomplish that, both `filterState` and `filterEnvironmentsByState`
    * functions work together.
    * The first one works as the filter that verifies if the given environment matches
    * the given state.
@@ -34,9 +34,9 @@
    * @param {Array} array
    * @return {Array}
    */
-  const filterEnvironmnetsByState = (fn, arr) => arr.map((item) => {
+  const filterEnvironmentsByState = (fn, arr) => arr.map((item) => {
     if (item.children) {
-      const filteredChildren = filterEnvironmnetsByState(fn, item.children).filter(Boolean);
+      const filteredChildren = filterEnvironmentsByState(fn, item.children).filter(Boolean);
       if (filteredChildren.length) {
         item.children = filteredChildren;
         return item;
@@ -76,12 +76,13 @@
         helpPagePath: environmentsData.helpPagePath,
         commitIconSvg: environmentsData.commitIconSvg,
         playIconSvg: environmentsData.playIconSvg,
+        terminalIconSvg: environmentsData.terminalIconSvg,
       };
     },
 
     computed: {
       filteredEnvironments() {
-        return filterEnvironmnetsByState(filterState(this.visibility), this.state.environments);
+        return filterEnvironmentsByState(filterState(this.visibility), this.state.environments);
       },
 
       scope() {
@@ -102,7 +103,7 @@
     },
 
     /**
-     * Fetches all the environmnets and stores them.
+     * Fetches all the environments and stores them.
      * Toggles loading property.
      */
     created() {
@@ -230,6 +231,7 @@
                     :can-create-deployment="canCreateDeploymentParsed"
                     :can-read-environment="canReadEnvironmentParsed"
                     :play-icon-svg="playIconSvg"
+                    :terminal-icon-svg="terminalIconSvg"
                     :commit-icon-svg="commitIconSvg"></tr>
 
                   <tr v-if="model.isOpen && model.children && model.children.length > 0"
@@ -240,6 +242,7 @@
                     :can-create-deployment="canCreateDeploymentParsed"
                     :can-read-environment="canReadEnvironmentParsed"
                     :play-icon-svg="playIconSvg"
+                    :terminal-icon-svg="terminalIconSvg"
                     :commit-icon-svg="commitIconSvg">
                     </tr>
 

app/assets/javascripts/environments/components/environment_item.js.es6

@@ -8,6 +8,7 @@
 /*= require ./environment_external_url */
 /*= require ./environment_stop */
 /*= require ./environment_rollback */
+/*= require ./environment_terminal_button */
 
 (() => {
   /**
@@ -33,6 +34,7 @@
       'external-url-component': window.gl.environmentsList.ExternalUrlComponent,
       'stop-component': window.gl.environmentsList.StopComponent,
       'rollback-component': window.gl.environmentsList.RollbackComponent,
+      'terminal-button-component': window.gl.environmentsList.TerminalButtonComponent,
     },
 
     props: {
@@ -68,6 +70,12 @@
         type: String,
         required: false,
       },
+
+      terminalIconSvg: {
+        type: String,
+        required: false,
+      },
+
     },
 
     data() {
@@ -506,6 +514,14 @@
               </stop-component>
             </div>
 
+            <div v-if="model.terminal_path"
+              class="inline js-terminal-button-container">
+              <terminal-button-component
+                :terminal-icon-svg="terminalIconSvg"
+                :terminal-path="model.terminal_path">
+              </terminal-button-component>
+            </div>
+
             <div v-if="canRetry && canCreateDeployment"
               class="inline js-rollback-component-container">
               <rollback-component

app/assets/javascripts/environments/components/environment_terminal_button.js.es6

+/*= require vue */
+/* global Vue */
+
+(() => {
+  window.gl = window.gl || {};
+  window.gl.environmentsList = window.gl.environmentsList || {};
+
+  window.gl.environmentsList.TerminalButtonComponent = Vue.component('terminal-button-component', {
+    props: {
+      terminalPath: {
+        type: String,
+        default: '',
+      },
+      terminalIconSvg: {
+        type: String,
+        default: '',
+      },
+    },
+
+    template: `
+      <a class="btn terminal-button"
+        :href="terminalPath">
+        <span class="js-terminal-icon-container" v-html="terminalIconSvg"></span>
+      </a>
+    `,
+  });
+})();

app/assets/javascripts/terminal/terminal.js.es6

+/* global Terminal */
+
+(() => {
+  class GLTerminal {
+
+    constructor(options) {
+      this.options = options || {};
+
+      this.options.cursorBlink = options.cursorBlink || true;
+      this.options.screenKeys = options.screenKeys || true;
+      this.container = document.querySelector(options.selector);
+
+      this.setSocketUrl();
+      this.createTerminal();
+      $(window).off('resize.terminal').on('resize.terminal', () => {
+        this.terminal.fit();
+      });
+    }
+
+    setSocketUrl() {
+      const { protocol, hostname, port } = window.location;
+      const wsProtocol = protocol === 'https:' ? 'wss://' : 'ws://';
+      const path = this.container.dataset.projectPath;
+
+      this.socketUrl = `${wsProtocol}${hostname}:${port}${path}`;
+    }
+
+    createTerminal() {
+      this.terminal = new Terminal(this.options);
+      this.socket = new WebSocket(this.socketUrl, ['terminal.gitlab.com']);
+      this.socket.binaryType = 'arraybuffer';
+
+      this.terminal.open(this.container);
+      this.socket.onopen = () => { this.runTerminal(); };
+      this.socket.onerror = () => { this.handleSocketFailure(); };
+    }
+
+    runTerminal() {
+      const decoder = new TextDecoder('utf-8');
+      const encoder = new TextEncoder('utf-8');
+
+      this.terminal.on('data', (data) => {
+        this.socket.send(encoder.encode(data));
+      });
+
+      this.socket.addEventListener('message', (ev) => {
+        this.terminal.write(decoder.decode(ev.data));
+      });
+
+      this.isTerminalInitialized = true;
+      this.terminal.fit();
+    }
+
+    handleSocketFailure() {
+      this.terminal.write('\r\nConnection failure');
+    }
+
+  }
+
+  window.gl = window.gl || {};
+  gl.Terminal = GLTerminal;
+})();

app/assets/javascripts/terminal/terminal_bundle.js.es6

+//= require xterm/xterm.js
+//= require xterm/fit.js
+//= require ./terminal.js
+
+$(() => new gl.Terminal({ selector: '#terminal' }));

app/assets/stylesheets/framework/buttons.scss

@@ -230,6 +230,13 @@
   }
 }
 
+.btn-terminal {
+  svg {
+    height: 14px;
+    width: 18px;
+  }
+}
+
 .btn-lg {
   padding: 12px 20px;
 }

app/assets/stylesheets/pages/pipelines.scss

@@ -734,3 +734,23 @@
     padding: 5px 5px 5px 7px;
   }
 }
+
+.terminal-icon {
+  margin-left: 3px;
+}
+
+.terminal-container {
+  .content-block {
+    border-bottom: none;
+  }
+
+  #terminal {
+    margin-top: 10px;
+    min-height: 450px;
+    box-sizing: border-box;
+
+    > div {
+      min-height: 450px;
+    }
+  }
+}

app/controllers/projects/environments_controller.rb

@@ -4,17 +4,19 @@ class Projects::EnvironmentsController < Projects::ApplicationController
   before_action :authorize_create_environment!, only: [:new, :create]
   before_action :authorize_create_deployment!, only: [:stop]
   before_action :authorize_update_environment!, only: [:edit, :update]
-  before_action :environment, only: [:show, :edit, :update, :stop]
+  before_action :authorize_admin_environment!, only: [:terminal, :terminal_websocket_authorize]
+  before_action :environment, only: [:show, :edit, :update, :stop, :terminal, :terminal_websocket_authorize]
+  before_action :verify_api_request!, only: :terminal_websocket_authorize
 
   def index
     @scope = params[:scope]
     @environments = project.environments
-  
+
     respond_to do |format|
       format.html
       format.json do
         render json: EnvironmentSerializer
-          .new(project: @project)
+          .new(project: @project, user: current_user)
           .represent(@environments)
       end
     end
@@ -56,8 +58,33 @@ class Projects::EnvironmentsController < Projects::ApplicationController
     redirect_to polymorphic_path([project.namespace.becomes(Namespace), project, new_action])
   end
 
+  def terminal
+    # Currently, this acts as a hint to load the terminal details into the cache
+    # if they aren't there already. In the future, users will need these details
+    # to choose between terminals to connect to.
+    @terminals = environment.terminals
+  end
+
+  # GET .../terminal.ws : implemented in gitlab-workhorse
+  def terminal_websocket_authorize
+    # Just return the first terminal for now. If the list is in the process of
+    # being looked up, this may result in a 404 response, so the frontend
+    # should retry those errors
+    terminal = environment.terminals.try(:first)
+    if terminal
+      set_workhorse_internal_api_content_type
+      render json: Gitlab::Workhorse.terminal_websocket(terminal)
+    else
+      render text: 'Not found', status: 404
+    end
+  end
+
   private
 
+  def verify_api_request!
+    Gitlab::Workhorse.verify_api_request!(request.headers)
+  end
+
   def environment_params
     params.require(:environment).permit(:name, :external_url)
   end

app/models/concerns/reactive_caching.rb

+# The ReactiveCaching concern is used to fetch some data in the background and
+# store it in the Rails cache, keeping it up-to-date for as long as it is being
+# requested.  If the data hasn't been requested for +reactive_cache_lifetime+,
+# it stop being refreshed, and then be removed.
+#
+# Example of use:
+#
+#    class Foo < ActiveRecord::Base
+#      include ReactiveCaching
+#
+#      self.reactive_cache_key = ->(thing) { ["foo", thing.id] }
+#
+#      after_save :clear_reactive_cache!
+#
+#      def calculate_reactive_cache
+#        # Expensive operation here. The return value of this method is cached
+#      end
+#
+#      def result
+#        with_reactive_cache do |data|
+#          # ...
+#        end
+#      end
+#    end
+#
+# In this example, the first time `#result` is called, it will return `nil`.
+# However, it will enqueue a background worker to call `#calculate_reactive_cache`
+# and set an initial cache lifetime of ten minutes.
+#
+# Each time the background job completes, it stores the return value of
+# `#calculate_reactive_cache`. It is also re-enqueued to run again after
+# `reactive_cache_refresh_interval`, so keeping the stored value up to date.
+# Calculations are never run concurrently.
+#
+# Calling `#result` while a value is in the cache will call the block given to
+# `#with_reactive_cache`, yielding the cached value. It will also extend the
+# lifetime by `reactive_cache_lifetime`.
+#
+# Once the lifetime has expired, no more background jobs will be enqueued and
+# calling `#result` will again return `nil` - starting the process all over
+# again
+module ReactiveCaching
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :reactive_cache_lease_timeout
+
+    class_attribute :reactive_cache_key
+    class_attribute :reactive_cache_lifetime
+    class_attribute :reactive_cache_refresh_interval
+
+    # defaults
+    self.reactive_cache_lease_timeout = 2.minutes
+
+    self.reactive_cache_refresh_interval = 1.minute
+    self.reactive_cache_lifetime = 10.minutes
+
+    def calculate_reactive_cache
+      raise NotImplementedError
+    end
+
+    def with_reactive_cache(&blk)
+      within_reactive_cache_lifetime do
+        data = Rails.cache.read(full_reactive_cache_key)
+        yield data if data.present?
+      end
+    ensure
+      Rails.cache.write(full_reactive_cache_key('alive'), true, expires_in: self.class.reactive_cache_lifetime)
+      ReactiveCachingWorker.perform_async(self.class, id)
+    end
+
+    def clear_reactive_cache!
+      Rails.cache.delete(full_reactive_cache_key)
+    end
+
+    def exclusively_update_reactive_cache!
+      locking_reactive_cache do
+        within_reactive_cache_lifetime do
+          enqueuing_update do
+            value = calculate_reactive_cache
+            Rails.cache.write(full_reactive_cache_key, value)
+          end
+        end
+      end
+    end
+
+    private
+
+    def full_reactive_cache_key(*qualifiers)
+      prefix = self.class.reactive_cache_key
+      prefix = prefix.call(self) if prefix.respond_to?(:call)
+
+      ([prefix].flatten + qualifiers).join(':')
+    end
+
+    def locking_reactive_cache
+      lease = Gitlab::ExclusiveLease.new(full_reactive_cache_key, timeout: reactive_cache_lease_timeout)
+      uuid = lease.try_obtain
+      yield if uuid
+    ensure
+      Gitlab::ExclusiveLease.cancel(full_reactive_cache_key, uuid)
+    end
+
+    def within_reactive_cache_lifetime
+      yield if Rails.cache.read(full_reactive_cache_key('alive'))
+    end
+
+    def enqueuing_update
+      yield
+    ensure
+      ReactiveCachingWorker.perform_in(self.class.reactive_cache_refresh_interval, self.class, id)
+    end
+  end
+end

app/models/environment.rb

@@ -128,6 +128,14 @@ class Environment < ActiveRecord::Base
     end
   end
 
+  def has_terminals?
+    project.deployment_service.present? && available? && last_deployment.present?
+  end
+
+  def terminals
+    project.deployment_service.terminals(self) if has_terminals?
+  end
+
   # An environment name is not necessarily suitable for use in URLs, DNS
   # or other third-party contexts, so provide a slugified version. A slug has
   # the following properties:

app/models/project_services/deployment_service.rb

@@ -12,4 +12,22 @@ class DeploymentService < Service
   def predefined_variables
     []
   end
+
+  # Environments may have a number of terminals. Should return an array of
+  # hashes describing them, e.g.:
+  #
+  #     [{
+  #       :selectors    => {"a" => "b", "foo" => "bar"},
+  #       :url          => "wss://external.example.com/exec",
+  #       :headers      => {"Authorization" => "Token xxx"},
+  #       :subprotocols => ["foo"],
+  #       :ca_pem       => "----BEGIN CERTIFICATE...", # optional
+  #       :created_at   => Time.now.utc
+  #     }]
+  #
+  # Selectors should be a set of values that uniquely identify a particular
+  # terminal
+  def terminals(environment)
+    raise NotImplementedError
+  end
 end

app/models/project_services/kubernetes_service.rb

 class KubernetesService < DeploymentService
+  include Gitlab::Kubernetes
+  include ReactiveCaching
+
+  self.reactive_cache_key = ->(service) { [ service.class.model_name.singular, service.project_id ] }
+
   # Namespace defaults to the project path, but can be overridden in case that
   # is an invalid or inappropriate name
   prop_accessor :namespace
@@ -25,6 +30,8 @@ class KubernetesService < DeploymentService
       length: 1..63
   end
 
+  after_save :clear_reactive_cache!
+
   def initialize_properties
     if properties.nil?
       self.properties = {}
@@ -41,7 +48,8 @@ class KubernetesService < DeploymentService
   end
 
   def help
-    ''
+    'To enable terminal access to Kubernetes environments, label your ' \
+    'deployments with `app=$CI_ENVIRONMENT_SLUG`'
   end
 
   def to_param
@@ -75,9 +83,9 @@ class KubernetesService < DeploymentService
 
   # Check we can connect to the Kubernetes API
   def test(*args)
-    kubeclient = build_kubeclient
-    kubeclient.discover
+    kubeclient = build_kubeclient!
 
+    kubeclient.discover
     { success: kubeclient.discovered, result: "Checked API discovery endpoint" }
   rescue => err
     { success: false, result: err }
@@ -93,20 +101,48 @@ class KubernetesService < DeploymentService
     variables
   end
 
-  private
+  # Constructs a list of terminals from the reactive cache
+  #
+  # Returns nil if the cache is empty, in which case you should try again a
+  # short time later
+  def terminals(environment)
+    with_reactive_cache do |data|
+      pods = data.fetch(:pods, nil)
+      filter_pods(pods, app: environment.slug).
+        flat_map { |pod| terminals_for_pod(api_url, namespace, pod) }.
+        map { |terminal| add_terminal_auth(terminal, token, ca_pem) }
+    end
+  end
 
-  def build_kubeclient(api_path = '/api', api_version = 'v1')
-    return nil unless api_url && namespace && token
+  # Caches all pods in the namespace so other calls don't need to block on
+  # network access.
+  def calculate_reactive_cache
+    return unless active? && project && !project.pending_delete?
 
-    url = URI.parse(api_url)
-    url.path = url.path[0..-2] if url.path[-1] == "/"
-    url.path += api_path
+    kubeclient = build_kubeclient!
+
+    # Store as hashes, rather than as third-party types
+    pods = begin
+      kubeclient.get_pods(namespace: namespace).as_json
+    rescue KubeException => err
+      raise err unless err.error_code == 404
+      []
+    end
+
+    # We may want to cache extra things in the future
+    { pods: pods }
+  end
+
+  private
+
+  def build_kubeclient!(api_path: 'api', api_version: 'v1')
+    raise "Incomplete settings" unless api_url && namespace && token
 
     ::Kubeclient::Client.new(
-      url,
+      join_api_url(api_path),
       api_version,
-      ssl_options: kubeclient_ssl_options,
       auth_options: kubeclient_auth_options,
+      ssl_options: kubeclient_ssl_options,
       http_proxy_uri: ENV['http_proxy']
     )
   end
@@ -125,4 +161,13 @@ class KubernetesService < DeploymentService
   def kubeclient_auth_options
     { bearer_token: token }
   end
+
+  def join_api_url(*parts)
+    url = URI.parse(api_url)
+    prefix = url.path.sub(%r{/+\z}, '')
+
+    url.path = [ prefix, *parts ].join("/")
+
+    url.to_s
+  end
 end

app/serializers/environment_entity.rb

@@ -23,5 +23,13 @@ class EnvironmentEntity < Grape::Entity
       environment)
   end
 
+  expose :terminal_path, if: ->(environment, _) { environment.has_terminals? } do |environment|
+    can?(request.user, :admin_environment, environment.project) &&
+      terminal_namespace_project_environment_path(
+        environment.project.namespace,
+        environment.project,
+        environment)
+  end
+
   expose :created_at, :updated_at
 end

app/serializers/request_aware_entity.rb

@@ -8,4 +8,8 @@ module RequestAwareEntity
   def request
     @options.fetch(:request)
   end
+
+  def can?(object, action, subject)
+    Ability.allowed?(object, action, subject)
+  end
 end

app/views/projects/environments/_terminal_button.html.haml

+- if environment.has_terminals? && can?(current_user, :admin_environment, @project)
+  = link_to terminal_namespace_project_environment_path(@project.namespace, @project, environment), class: 'btn terminal-button' do
+    = icon('terminal')

app/views/projects/environments/index.html.haml

@@ -4,10 +4,6 @@
 
 - content_for :page_specific_javascripts do
   = page_specific_javascript_tag("environments/environments_bundle.js")
-.commit-icon-svg.hidden
-  = custom_icon("icon_commit")
-.play-icon-svg.hidden
-  = custom_icon("icon_play")
 
 #environments-list-view{ data: { environments_data: environments_list_data,
   "can-create-deployment" => can?(current_user, :create_deployment, @project).to_s,
@@ -19,4 +15,5 @@
   "help-page-path" => help_page_path("ci/environments"),
   "css-class" => container_class,
   "commit-icon-svg" => custom_icon("icon_commit"),
+  "terminal-icon-svg" => custom_icon("icon_terminal"),
   "play-icon-svg" => custom_icon("icon_play")}}

app/views/projects/environments/show.html.haml

@@ -8,6 +8,7 @@
       %h3.page-title= @environment.name.capitalize
     .col-md-3
       .nav-controls
+        = render 'projects/environments/terminal_button', environment: @environment
         = render 'projects/environments/external_url', environment: @environment
         - if can?(current_user, :update_environment, @environment)
           = link_to 'Edit', edit_namespace_project_environment_path(@project.namespace, @project, @environment), class: 'btn'

app/views/projects/environments/terminal.html.haml

+- @no_container = true
+- page_title "Terminal for environment", @environment.name
+= render "projects/pipelines/head"
+
+- content_for :page_specific_javascripts do
+  = stylesheet_link_tag "xterm/xterm"
+  = page_specific_javascript_tag("terminal/terminal_bundle.js")
+
+%div{class: container_class}
+  .top-area
+    .row
+      .col-sm-6
+        %h3.page-title
+          Terminal for environment
+          = @environment.name
+
+      .col-sm-6
+        .nav-controls
+          = render 'projects/deployments/actions', deployment: @environment.last_deployment
+
+.terminal-container{class: container_class}
+  #terminal{data:{project_path: "#{terminal_namespace_project_environment_path(@project.namespace, @project, @environment)}.ws"}}

app/views/shared/icons/_icon_terminal.svg

+<svg width="19" height="14" viewBox="0 0 19 14" xmlns="http://www.w3.org/2000/svg"><rect fill="#848484" x="7.2" y="9.25" width="6.46" height="1.5" rx=".5"/><path d="M5.851 7.016L3.81 9.103a.503.503 0 0 0 .017.709l.35.334c.207.198.524.191.717-.006l2.687-2.748a.493.493 0 0 0 .137-.376.493.493 0 0 0-.137-.376L4.894 3.892a.507.507 0 0 0-.717-.006l-.35.334a.503.503 0 0 0-.017.709L5.85 7.016z"/><path d="M1.25 11.497c0 .691.562 1.253 1.253 1.253h13.994c.694 0 1.253-.56 1.253-1.253V2.503c0-.691-.562-1.253-1.253-1.253H2.503c-.694 0-1.253.56-1.253 1.253v8.994zM2.503 0h13.994A2.504 2.504 0 0 1 19 2.503v8.994A2.501 2.501 0 0 1 16.497 14H2.503A2.504 2.504 0 0 1 0 11.497V2.503A2.501 2.501 0 0 1 2.503 0z"/></svg>

app/workers/reactive_caching_worker.rb

+class ReactiveCachingWorker
+  include Sidekiq::Worker
+  include DedicatedSidekiqQueue
+
+  def perform(class_name, id)
+    klass = begin
+      Kernel.const_get(class_name)
+    rescue NameError
+      nil
+    end
+    return unless klass
+
+    klass.find_by(id: id).try(:exclusively_update_reactive_cache!)
+  end
+end

changelogs/unreleased/nick-thomas-gitlab-ce-22864-kubernetes-deploy-with-terminal.yml

+---
+title: Add online terminal support for Kubernetes
+merge_request: 7690
+author: 

config/application.rb

@@ -89,6 +89,7 @@ module Gitlab
     config.assets.precompile << "mailers/*.css"
     config.assets.precompile << "katex.css"
     config.assets.precompile << "katex.js"
+    config.assets.precompile << "xterm/xterm.css"
     config.assets.precompile << "graphs/graphs_bundle.js"
     config.assets.precompile << "users/users_bundle.js"
     config.assets.precompile << "network/network_bundle.js"
@@ -102,6 +103,7 @@ module Gitlab
     config.assets.precompile << "environments/environments_bundle.js"
     config.assets.precompile << "blob_edit/blob_edit_bundle.js"
     config.assets.precompile << "snippet/snippet_bundle.js"
+    config.assets.precompile << "terminal/terminal_bundle.js"
     config.assets.precompile << "lib/utils/*.js"
     config.assets.precompile << "lib/*.js"
     config.assets.precompile << "u2f.js"

config/routes/project.rb

@@ -148,6 +148,8 @@ constraints(ProjectUrlConstrainer.new) do
       resources :environments, except: [:destroy] do
         member do
           post :stop
+          get :terminal
+          get '/terminal.ws/authorize', to: 'environments#terminal_websocket_authorize', constraints: { format: nil }
         end
       end
 

config/sidekiq_queues.yml

@@ -46,5 +46,6 @@
   - [repository_check, 1]
   - [system_hook, 1]
   - [git_garbage_collect, 1]
+  - [reactive_caching, 1]
   - [cronjob, 1]
   - [default, 1]

doc/README.md

@@ -34,6 +34,7 @@
 - [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter.
 - [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages.
 - [Koding](administration/integration/koding.md) Set up Koding to use with GitLab.
+- [Online terminals](administration/integration/terminal.md) Provide terminal access to environments from within GitLab.
 - [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
 - [Log system](administration/logs.md) Log system.
 - [Environment Variables](administration/environment_variables.md) to configure GitLab.

doc/administration/high_availability/load_balancer.md

@@ -10,11 +10,11 @@ you need to use with GitLab.
 
 ## Basic ports
 
-| LB Port | Backend Port | Protocol   |
-| ------- | ------------ | --------   |
-| 80      | 80           | HTTP       |
-| 443     | 443          | HTTPS [^1] |
-| 22      | 22           | TCP        |
+| LB Port | Backend Port | Protocol        |
+| ------- | ------------ | --------------- |
+| 80      | 80           | HTTP  [^1]      |
+| 443     | 443          | HTTPS [^1] [^2] |
+| 22      | 22           | TCP             |
 
 ## GitLab Pages Ports
 
@@ -25,8 +25,8 @@ GitLab Pages requires a separate VIP. Configure DNS to point the
 
 | LB Port | Backend Port | Protocol |
 | ------- | ------------ | -------- |
-| 80      | Varies [^2]  | HTTP     |
-| 443     | Varies [^2]  | TCP [^3] |
+| 80      | Varies [^3]  | HTTP     |
+| 443     | Varies [^3]  | TCP [^4] |
 
 ## Alternate SSH Port
 
@@ -50,13 +50,19 @@ Read more on high-availability configuration:
 1. [Configure NFS](nfs.md)
 1. [Configure the GitLab application servers](gitlab.md)
 
-[^1]: When using HTTPS protocol for port 443, you will need to add an SSL
+[^1]: [Terminal support](../../ci/environments.md#terminal-support) requires
+      your load balancer to correctly handle WebSocket connections. When using
+      HTTP or HTTPS proxying, this means your load balancer must be configured
+      to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the
+      [online terminal](../integration/terminal.md) integration guide for
+      more details.
+[^2]: When using HTTPS protocol for port 443, you will need to add an SSL
       certificate to the load balancers. If you wish to terminate SSL at the
       GitLab application server instead, use TCP protocol.
-[^2]: The backend port for GitLab Pages depends on the
+[^3]: The backend port for GitLab Pages depends on the
       `gitlab_pages['external_http']` and `gitlab_pages['external_https']`
       setting. See [GitLab Pages documentation][gitlab-pages] for more details.
-[^3]: Port 443 for GitLab Pages should always use the TCP protocol. Users can
+[^4]: Port 443 for GitLab Pages should always use the TCP protocol. Users can
       configure custom domains with custom SSL, which would not be possible
       if SSL was terminated at the load balancer.
 

doc/administration/integration/terminal.md

+# Online terminals
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690)
+in GitLab 8.15. Only project masters and owners can access online terminals.
+
+With the introduction of the [Kubernetes](../../project_services/kubernetes.md)
+project service, GitLab gained the ability to store and use credentials for a
+Kubernetes cluster. One of the things it uses these credentials for is providing
+access to [online terminals](../../ci/environments.html#online-terminals)
+for environments.
+
+## How it works
+
+A detailed overview of the architecture of online terminals and how they work
+can be found in [this document](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/doc/terminal.md).
+In brief:
+
+* GitLab relies on the user to provide their own Kubernetes credentials, and to
+  appropriately label the pods they create when deploying.
+* When a user navigates to the terminal page for an environment, they are served
+  a JavaScript application that opens a WebSocket connection back to GitLab.
+* The WebSocket is handled in [Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse),
+   rather than the Rails application server.
+* Workhorse queries Rails for connection details and user permissions; Rails
+  queries Kubernetes for them in the background, using [Sidekiq](../troubleshooting/sidekiq.md)
+* Workhorse acts as a proxy server between the user's browser and the Kubernetes
+  API, passing WebSocket frames between the two.
+* Workhorse regularly polls Rails, terminating the WebSocket connection if the
+  user no longer has permission to access the terminal, or if the connection
+  details have changed.
+
+##  Enabling and disabling terminal support
+
+As online terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of
+Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers
+through to the next one in the chain. If you installed Gitlab using Omnibus, or
+from source, starting with GitLab 8.15, this should be done by the default
+configuration, so there's no need for you to do anything.
+
+However, if you run a [load balancer](../high_availability/load_balancer.md) in
+front of GitLab, you may need to make some changes to your configuration. These
+guides document the necessary steps for a selection of popular reverse proxies:
+
+* [Apache](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html)
+* [NGINX](https://www.nginx.com/blog/websocket-nginx/)
+* [HAProxy](http://blog.haproxy.com/2012/11/07/websockets-load-balancing-with-haproxy/)
+* [Varnish](https://www.varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html)
+
+Workhorse won't let WebSocket requests through to non-WebSocket endpoints, so
+it's safe to enable support for these headers globally. If you'd rather had a
+narrower set of rules, you can restrict it to URLs ending with `/terminal.ws`
+(although this may still have a few false positives).
+
+If you installed from source, or have made any configuration changes to your
+Omnibus installation before upgrading to 8.15, you may need to make some
+changes to your configuration. See the  [8.14 to 8.15 upgrade](../../update/8.14-to-8.15.md#nginx-configuration)
+document for more details.
+
+If you'd like to disable online terminal support in GitLab, just stop passing
+the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse
+proxy in the chain. For most users, this will be the NGINX server bundled with
+Omnibus Gitlab, in which case, you need to:
+
+* Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file
+* Ensure the whole block is uncommented, and then comment out or remove the
+  `Connection` and `Upgrade` lines.
+
+For your own load balancer, just reverse the configuration changes recommended
+by the above guides.
+
+When these headers are not passed through, Workhorse will return a
+`400 Bad Request` response to users attempting to use an online terminal. In
+turn, they will receive a `Connection failed` message.

doc/ci/environments.md

@@ -25,7 +25,9 @@ Environments are like tags for your CI jobs, describing where code gets deployed
 Deployments are created when [jobs] deploy versions of code to environments,
 so every environment can have one or more deployments. GitLab keeps track of
 your deployments, so you always know what is currently being deployed on your
-servers.
+servers. If you have a deployment service such as [Kubernetes][kubernetes-service]
+enabled for your project, you can use it to assist with your deployments, and
+can even access a terminal for your environment from within GitLab!
 
 To better understand how environments and deployments work, let's consider an
 example. We assume that you have already created a project in GitLab and set up
@@ -233,6 +235,46 @@ Remember that if your environment's name is `production` (all lowercase), then
 it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).
 Double the benefit!
 
+## Terminal support
+
+>**Note:**
+Terminal support was added in GitLab 8.15 and is only available to project
+masters and owners.
+
+If you deploy to your environments with the help of a deployment service (e.g.,
+the [Kubernetes](../project_services/kubernetes.md) service), GitLab can open
+a terminal session to your environment! This is a very powerful feature that
+allows you to debug issues without leaving the comfort of your web browser. To
+enable it, just follow the instructions given in the service documentation.
+
+Once enabled, your environments will gain a "terminal" button:
+
+![Terminal button on environment index](img/environments_terminal_button_on_index.png)
+
+You can also access the terminal button from the page for a specific environment:
+
+![Terminal button for an environment](img/environments_terminal_button_on_show.png)
+
+Wherever you find it, clicking the button will take you to a separate page to
+establish the terminal session:
+
+![Terminal page](img/environments_terminal_page.png)
+
+This works just like any other terminal - you'll be in the container created
+by your deployment, so you can run shell commands and get responses in real
+time, check the logs, try out configuration or code tweaks, etc. You can open
+multiple terminals to the same environment - they each get their own shell
+session -  and even a multiplexer like `screen` or `tmux`!  
+
+>**Note:**
+Container-based deployments often lack basic tools (like an editor), and may
+be stopped or restarted at any time. If this happens, you will lose all your
+changes! Treat this as a debugging tool, not a comprehensive online IDE. You
+can use [Koding](../administration/integration/koding.md) for online
+development.
+
+---
+
 While this is fine for deploying to some stable environments like staging or
 production, what happens for branches? So far we haven't defined anything
 regarding deployments for branches other than `master`. Dynamic environments
@@ -524,6 +566,7 @@ Below are some links you may find interesting:
 [Pipelines]: pipelines.md
 [jobs]: yaml/README.md#jobs
 [yaml]: yaml/README.md
+[kubernetes-service]: ../project_services/kubernetes.md]
 [environments]: #environments
 [deployments]: #deployments
 [permissions]: ../user/permissions.md

doc/project_services/kubernetes.md

@@ -47,3 +47,17 @@ GitLab CI build environment:
 - `KUBE_TOKEN`
 - `KUBE_NAMESPACE`
 - `KUBE_CA_PEM` - only if a custom CA bundle was specified
+
+## Terminal support
+
+>**NOTE:**
+Added in GitLab 8.15. You must be the project owner or have `master` permissions
+to use terminals. Support is currently limited to the first container in the
+first pod of your environment.
+
+When enabled, the Kubernetes service adds online [terminal support](../ci/environments.md#terminal-support)
+to your environments. This is based on the `exec` functionality found in
+Docker and Kubernetes, so you get a new shell session within your existing
+containers. To use this integration, you should deploy to Kubernetes using
+the deployment variables above, ensuring any pods you create are labelled with
+`app=$CI_ENVIRONMENT_SLUG`.

doc/user/permissions.md

@@ -33,6 +33,7 @@ The following table depicts the various user permission levels in a project.
 | See a container registry              |         | ✓          | ✓           | ✓        | ✓      |
 | See environments                      |         | ✓          | ✓           | ✓        | ✓      |
 | Create new environments               |         |            | ✓           | ✓        | ✓      |
+| Use environment terminals             |         |            |             | ✓        | ✓      |
 | Stop environments                     |         |            | ✓           | ✓        | ✓      |
 | See a list of merge requests          |         | ✓          | ✓           | ✓        | ✓      |
 | Manage/Accept merge requests          |         |            | ✓           | ✓        | ✓      |

lib/gitlab/kubernetes.rb

+module Gitlab
+  # Helper methods to do with Kubernetes network services & resources
+  module Kubernetes
+    # This is the comand that is run to start a terminal session. Kubernetes
+    # expects `command=foo&command=bar, not `command[]=foo&command[]=bar`
+    EXEC_COMMAND = URI.encode_www_form(
+      ['sh', '-c', 'bash || sh'].map { |value| ['command', value] }
+    )
+
+    # Filters an array of pods (as returned by the kubernetes API) by their labels
+    def filter_pods(pods, labels = {})
+      pods.select do |pod|
+        metadata = pod.fetch("metadata", {})
+        pod_labels = metadata.fetch("labels", nil)
+        next unless pod_labels
+
+        labels.all? { |k, v| pod_labels[k.to_s] == v }
+      end
+    end
+
+    # Converts a pod (as returned by the kubernetes API) into a terminal
+    def terminals_for_pod(api_url, namespace, pod)
+      metadata = pod.fetch("metadata", {})
+      status   = pod.fetch("status", {})
+      spec     = pod.fetch("spec", {})
+
+      containers = spec["containers"]
+      pod_name   = metadata["name"]
+      phase      = status["phase"]
+
+      return unless containers.present? && pod_name.present? && phase == "Running"
+
+      created_at = DateTime.parse(metadata["creationTimestamp"]) rescue nil
+
+      containers.map do |container|
+        {
+          selectors:    { pod: pod_name, container: container["name"] },
+          url:          container_exec_url(api_url, namespace, pod_name, container["name"]),
+          subprotocols: ['channel.k8s.io'],
+          headers:      Hash.new { |h, k| h[k] = [] },
+          created_at:   created_at,
+        }
+      end
+    end
+
+    def add_terminal_auth(terminal, token, ca_pem = nil)
+      terminal[:headers]['Authorization'] << "Bearer #{token}"
+      terminal[:ca_pem] = ca_pem if ca_pem.present?
+      terminal
+    end
+
+    def container_exec_url(api_url, namespace, pod_name, container_name)
+      url = URI.parse(api_url)
+      url.path = [
+        url.path.sub(%r{/+\z}, ''),
+        'api', 'v1',
+        'namespaces', ERB::Util.url_encode(namespace),
+        'pods', ERB::Util.url_encode(pod_name),
+        'exec'
+      ].join('/')
+
+      url.query = {
+        container: container_name,
+        tty: true,
+        stdin: true,
+        stdout: true,
+        stderr: true,
+      }.to_query + '&' + EXEC_COMMAND
+
+      case url.scheme
+      when 'http'
+        url.scheme = 'ws'
+      when 'https'
+        url.scheme = 'wss'
+      end
+
+      url.to_s
+    end
+  end
+end

lib/gitlab/workhorse.rb

@@ -95,6 +95,19 @@ module Gitlab
         ]
       end
 
+      def terminal_websocket(terminal)
+        details = {
+          'Terminal' => {
+            'Subprotocols' => terminal[:subprotocols],
+            'Url' => terminal[:url],
+            'Header' => terminal[:headers]
+          }
+        }
+        details['Terminal']['CAPem'] = terminal[:ca_pem] if terminal.has_key?(:ca_pem)
+
+        details
+      end
+
       def version
         path = Rails.root.join(VERSION_FILE)
         path.readable? ? path.read.chomp : 'unknown'

spec/controllers/projects/environments_controller_spec.rb

@@ -71,6 +71,75 @@ describe Projects::EnvironmentsController do
     end
   end
 
+  describe 'GET #terminal' do
+    context 'with valid id' do
+      it 'responds with a status code 200' do
+        get :terminal, environment_params
+
+        expect(response).to have_http_status(200)
+      end
+
+      it 'loads the terminals for the enviroment' do
+        expect_any_instance_of(Environment).to receive(:terminals)
+
+        get :terminal, environment_params
+      end
+    end
+
+    context 'with invalid id' do
+      it 'responds with a status code 404' do
+        get :terminal, environment_params(id: 666)
+
+        expect(response).to have_http_status(404)
+      end
+    end
+  end
+
+  describe 'GET #terminal_websocket_authorize' do
+    context 'with valid workhorse signature' do
+      before do
+        allow(Gitlab::Workhorse).to receive(:verify_api_request!).and_return(nil)
+      end
+
+      context 'and valid id' do
+        it 'returns the first terminal for the environment' do
+          expect_any_instance_of(Environment).
+            to receive(:terminals).
+            and_return([:fake_terminal])
+
+          expect(Gitlab::Workhorse).
+            to receive(:terminal_websocket).
+            with(:fake_terminal).
+            and_return(workhorse: :response)
+
+          get :terminal_websocket_authorize, environment_params
+
+          expect(response).to have_http_status(200)
+          expect(response.headers["Content-Type"]).to eq(Gitlab::Workhorse::INTERNAL_API_CONTENT_TYPE)
+          expect(response.body).to eq('{"workhorse":"response"}')
+        end
+      end
+
+      context 'and invalid id' do
+        it 'returns 404' do
+          get :terminal_websocket_authorize, environment_params(id: 666)
+
+          expect(response).to have_http_status(404)
+        end
+      end
+    end
+
+    context 'with invalid workhorse signature' do
+      it 'aborts with an exception' do
+        allow(Gitlab::Workhorse).to receive(:verify_api_request!).and_raise(JWT::DecodeError)
+
+        expect { get :terminal_websocket_authorize, environment_params }.to raise_error(JWT::DecodeError)
+        # controller tests don't set the response status correctly. It's enough
+        # to check that the action raised an exception
+      end
+    end
+  end
+
   def environment_params(opts = {})
     opts.reverse_merge(namespace_id: project.namespace,
                        project_id: project,

spec/factories/projects.rb

@@ -42,6 +42,12 @@ FactoryGirl.define do
       end
     end
 
+    trait :test_repo do
+      after :create do |project|
+        TestEnv.copy_repo(project)
+      end
+    end
+
     # Nest Project Feature attributes
     transient do
       wiki_access_level ProjectFeature::ENABLED
@@ -91,9 +97,7 @@ FactoryGirl.define do
   factory :project, parent: :empty_project do
     path { 'gitlabhq' }
 
-    after :create do |project|
-      TestEnv.copy_repo(project)
-    end
+    test_repo
   end
 
   factory :forked_project_with_submodules, parent: :empty_project do
@@ -140,7 +144,7 @@ FactoryGirl.define do
         active: true,
         properties: {
           namespace: project.path,
-          api_url: 'https://kubernetes.example.com/api',
+          api_url: 'https://kubernetes.example.com',
           token: 'a' * 40,
         }
       )

spec/features/environment_spec.rb

@@ -38,6 +38,10 @@ feature 'Environment', :feature do
         scenario 'does not show a re-deploy button for deployment without build' do
           expect(page).not_to have_link('Re-deploy')
         end
+
+        scenario 'does not show terminal button' do
+          expect(page).not_to have_terminal_button
+        end
       end
 
       context 'with related deployable present' do
@@ -60,6 +64,10 @@ feature 'Environment', :feature do
           expect(page).not_to have_link('Stop')
         end
 
+        scenario 'does not show terminal button' do
+          expect(page).not_to have_terminal_button
+        end
+
         context 'with manual action' do
           given(:manual) { create(:ci_build, :manual, pipeline: pipeline, name: 'deploy to production') }
 
@@ -84,6 +92,26 @@ feature 'Environment', :feature do
             end
           end
 
+          context 'with terminal' do
+            let(:project) { create(:kubernetes_project, :test_repo) }
+
+            context 'for project master' do
+              let(:role) { :master }
+
+              scenario 'it shows the terminal button' do
+                expect(page).to have_terminal_button
+              end
+            end
+
+            context 'for developer' do
+              let(:role) { :developer }
+
+              scenario 'does not show terminal button' do
+                expect(page).not_to have_terminal_button
+              end
+            end
+          end
+
           context 'with stop action' do
             given(:manual) { create(:ci_build, :manual, pipeline: pipeline, name: 'close_app') }
             given(:deployment) { create(:deployment, environment: environment, deployable: build, on_stop: 'close_app') }
@@ -158,4 +186,8 @@ feature 'Environment', :feature do
                                              environment.project,
                                              environment)
   end
+
+  def have_terminal_button
+    have_link(nil, href: terminal_namespace_project_environment_path(project.namespace, project, environment))
+  end
 end

spec/features/environments_spec.rb

@@ -113,6 +113,10 @@ feature 'Environments page', :feature, :js do
           expect(page).not_to have_css('external-url')
         end
 
+        scenario 'does not show terminal button' do
+          expect(page).not_to have_terminal_button
+        end
+
         context 'with external_url' do
           given(:environment) { create(:environment, project: project, external_url: 'https://git.gitlab.com') }
           given(:build) { create(:ci_build, pipeline: pipeline) }
@@ -145,6 +149,26 @@ feature 'Environments page', :feature, :js do
             end
           end
         end
+
+        context 'with terminal' do
+          let(:project) { create(:kubernetes_project, :test_repo) }
+
+          context 'for project master' do
+            let(:role) { :master }
+
+            scenario 'it shows the terminal button' do
+              expect(page).to have_terminal_button
+            end
+          end
+
+          context 'for developer' do
+            let(:role) { :developer }
+
+            scenario 'does not show terminal button' do
+              expect(page).not_to have_terminal_button
+            end
+          end
+        end
       end
     end
   end
@@ -195,6 +219,10 @@ feature 'Environments page', :feature, :js do
     end
   end
 
+  def have_terminal_button
+    have_link(nil, href: terminal_namespace_project_environment_path(project.namespace, project, environment))
+  end
+
   def visit_environments(project)
     visit namespace_project_environments_path(project.namespace, project)
   end

spec/lib/gitlab/kubernetes_spec.rb

+require 'spec_helper'
+
+describe Gitlab::Kubernetes do
+  include described_class
+
+  describe '#container_exec_url' do
+    let(:api_url) { 'https://example.com' }
+    let(:namespace) { 'default' }
+    let(:pod_name) { 'pod1' }
+    let(:container_name) { 'container1' }
+
+    subject(:result) { URI::parse(container_exec_url(api_url, namespace, pod_name, container_name)) }
+
+    it { expect(result.scheme).to eq('wss') }
+    it { expect(result.host).to eq('example.com') }
+    it { expect(result.path).to eq('/api/v1/namespaces/default/pods/pod1/exec') }
+    it { expect(result.query).to eq('container=container1&stderr=true&stdin=true&stdout=true&tty=true&command=sh&command=-c&command=bash+%7C%7C+sh') }
+
+    context 'with a HTTP API URL' do
+      let(:api_url) { 'http://example.com' }
+
+      it { expect(result.scheme).to eq('ws') }
+    end
+
+    context 'with a path prefix in the API URL' do
+      let(:api_url) { 'https://example.com/prefix/' }
+      it { expect(result.path).to eq('/prefix/api/v1/namespaces/default/pods/pod1/exec') }
+    end
+
+    context 'with arguments that need urlencoding' do
+      let(:namespace) { 'default namespace' }
+      let(:pod_name) { 'pod 1' }
+      let(:container_name) { 'container 1' }
+
+      it { expect(result.path).to eq('/api/v1/namespaces/default%20namespace/pods/pod%201/exec') }
+      it { expect(result.query).to match(/\Acontainer=container\+1&/) }
+    end
+  end
+end

spec/lib/gitlab/workhorse_spec.rb

@@ -37,6 +37,42 @@ describe Gitlab::Workhorse, lib: true do
     end
   end
 
+  describe '.terminal_websocket' do
+    def terminal(ca_pem: nil)
+      out = {
+        subprotocols: ['foo'],
+        url: 'wss://example.com/terminal.ws',
+        headers: { 'Authorization' => ['Token x'] }
+      }
+      out[:ca_pem] = ca_pem if ca_pem
+      out
+    end
+
+    def workhorse(ca_pem: nil)
+      out = {
+        'Terminal' => {
+          'Subprotocols' => ['foo'],
+          'Url' => 'wss://example.com/terminal.ws',
+          'Header' => { 'Authorization' => ['Token x'] }
+        }
+      }
+      out['Terminal']['CAPem'] = ca_pem if ca_pem
+      out
+    end
+
+    context 'without ca_pem' do
+      subject { Gitlab::Workhorse.terminal_websocket(terminal) }
+
+      it { is_expected.to eq(workhorse) }
+    end
+
+    context 'with ca_pem' do
+      subject { Gitlab::Workhorse.terminal_websocket(terminal(ca_pem: "foo")) }
+
+      it { is_expected.to eq(workhorse(ca_pem: "foo")) }
+    end
+  end
+
   describe '.send_git_diff' do
     let(:diff_refs) { double(base_sha: "base", head_sha: "head") }
     subject { described_class.send_git_patch(repository, diff_refs) }

spec/models/concerns/reactive_caching_spec.rb

+require 'spec_helper'
+
+describe ReactiveCaching, caching: true do
+  include ReactiveCachingHelpers
+
+  class CacheTest
+    include ReactiveCaching
+
+    self.reactive_cache_key = ->(thing) { ["foo", thing.id] }
+
+    self.reactive_cache_lifetime = 5.minutes
+    self.reactive_cache_refresh_interval = 15.seconds
+
+    attr_reader :id
+
+    def initialize(id, &blk)
+      @id = id
+      @calculator = blk
+    end
+
+    def calculate_reactive_cache
+      @calculator.call
+    end
+
+    def result
+      with_reactive_cache do |data|
+        data / 2
+      end
+    end
+  end
+
+  let(:now) { Time.now.utc }
+
+  around(:each) do |example|
+    Timecop.freeze(now) { example.run }
+  end
+
+  let(:calculation) { -> { 2 + 2 } }
+  let(:cache_key) { "foo:666" }
+  let(:instance) { CacheTest.new(666, &calculation) }
+
+  describe '#with_reactive_cache' do
+    before { stub_reactive_cache }
+    subject(:go!) { instance.result }
+
+    context 'when cache is empty' do
+      it { is_expected.to be_nil }
+
+      it 'queues a background worker' do
+        expect(ReactiveCachingWorker).to receive(:perform_async).with(CacheTest, 666)
+
+        go!
+      end
+
+      it 'updates the cache lifespan' do
+        go!
+
+        expect(reactive_cache_alive?(instance)).to be_truthy
+      end
+    end
+
+    context 'when the cache is full' do
+      before { stub_reactive_cache(instance, 4) }
+
+      it { is_expected.to eq(2) }
+
+      context 'and expired' do
+        before { invalidate_reactive_cache(instance) }
+        it { is_expected.to be_nil }
+      end
+    end
+  end
+
+  describe '#clear_reactive_cache!' do
+    before do
+      stub_reactive_cache(instance, 4)
+      instance.clear_reactive_cache!
+    end
+
+    it { expect(instance.result).to be_nil }
+  end
+
+  describe '#exclusively_update_reactive_cache!' do
+    subject(:go!) { instance.exclusively_update_reactive_cache! }
+
+    context 'when the lease is free and lifetime is not exceeded' do
+      before { stub_reactive_cache(instance, "preexisting") }
+
+      it 'takes and releases the lease' do
+        expect_any_instance_of(Gitlab::ExclusiveLease).to receive(:try_obtain).and_return("000000")
+        expect(Gitlab::ExclusiveLease).to receive(:cancel).with(cache_key, "000000")
+
+        go!
+      end
+
+      it 'caches the result of #calculate_reactive_cache' do
+        go!
+
+        expect(read_reactive_cache(instance)).to eq(calculation.call)
+      end
+
+      it "enqueues a repeat worker" do
+        expect_reactive_cache_update_queued(instance)
+
+        go!
+      end
+
+      context 'and #calculate_reactive_cache raises an exception' do
+        before { stub_reactive_cache(instance, "preexisting") }
+        let(:calculation) { -> { raise "foo"} }
+
+        it 'leaves the cache untouched' do
+          expect { go! }.to raise_error("foo")
+          expect(read_reactive_cache(instance)).to eq("preexisting")
+        end
+
+        it 'enqueues a repeat worker' do
+          expect_reactive_cache_update_queued(instance)
+
+          expect { go! }.to raise_error("foo")
+        end
+      end
+    end
+
+    context 'when lifetime is exceeded' do
+      it 'skips the calculation' do
+        expect(instance).to receive(:calculate_reactive_cache).never
+
+        go!
+      end
+    end
+
+    context 'when the lease is already taken' do
+      before do
+        expect_any_instance_of(Gitlab::ExclusiveLease).to receive(:try_obtain).and_return(nil)
+      end
+
+      it 'skips the calculation' do
+        expect(instance).to receive(:calculate_reactive_cache).never
+
+        go!
+      end
+    end
+  end
+end

spec/models/environment_spec.rb

 require 'spec_helper'
 
 describe Environment, models: true do
-  subject(:environment) { create(:environment) }
+  let(:project) { create(:empty_project) }
+  subject(:environment) { create(:environment, project: project) }
 
   it { is_expected.to belong_to(:project) }
   it { is_expected.to have_many(:deployments) }
@@ -31,6 +32,8 @@ describe Environment, models: true do
   end
 
   describe '#includes_commit?' do
+    let(:project) { create(:project) }
+
     context 'without a last deployment' do
       it "returns false" do
         expect(environment.includes_commit?('HEAD')).to be false
@@ -38,9 +41,6 @@ describe Environment, models: true do
     end
 
     context 'with a last deployment' do
-      let(:project)     { create(:project) }
-      let(:environment) { create(:environment, project: project) }
-
       let!(:deployment) do
         create(:deployment, environment: environment, sha: project.commit('master').id)
       end
@@ -65,7 +65,6 @@ describe Environment, models: true do
 
   describe '#first_deployment_for' do
     let(:project)       { create(:project) }
-    let!(:environment)  { create(:environment, project: project) }
     let!(:deployment)   { create(:deployment, environment: environment, ref: commit.parent.id) }
     let!(:deployment1)  { create(:deployment, environment: environment, ref: commit.id) }
     let(:head_commit)   { project.commit }
@@ -196,6 +195,57 @@ describe Environment, models: true do
     end
   end
 
+  describe '#has_terminals?' do
+    subject { environment.has_terminals? }
+
+    context 'when the enviroment is available' do
+      context 'with a deployment service' do
+        let(:project) { create(:kubernetes_project) }
+
+        context 'and a deployment' do
+          let!(:deployment) { create(:deployment, environment: environment) }
+          it { is_expected.to be_truthy }
+        end
+
+        context 'but no deployments' do
+          it { is_expected.to be_falsy }
+        end
+      end
+
+      context 'without a deployment service' do
+        it { is_expected.to be_falsy }
+      end
+    end
+
+    context 'when the environment is unavailable' do
+      let(:project) { create(:kubernetes_project) }
+      before { environment.stop }
+      it { is_expected.to be_falsy }
+    end
+  end
+
+  describe '#terminals' do
+    let(:project) { create(:kubernetes_project) }
+    subject { environment.terminals }
+
+    context 'when the environment has terminals' do
+      before { allow(environment).to receive(:has_terminals?).and_return(true) }
+
+      it 'returns the terminals from the deployment service' do
+        expect(project.deployment_service).
+          to receive(:terminals).with(environment).
+          and_return(:fake_terminals)
+
+        is_expected.to eq(:fake_terminals)
+      end
+    end
+
+    context 'when the environment does not have terminals' do
+      before { allow(environment).to receive(:has_terminals?).and_return(false) }
+      it { is_expected.to eq(nil) }
+    end
+  end
+
   describe '#slug' do
     it "is automatically generated" do
       expect(environment.slug).not_to be_nil

spec/models/project_services/kubernetes_service_spec.rb

 require 'spec_helper'
 
-describe KubernetesService, models: true do
-  let(:project) { create(:empty_project) }
+describe KubernetesService, models: true, caching: true do
+  include KubernetesHelpers
+  include ReactiveCachingHelpers
+
+  let(:project) { create(:kubernetes_project) }
+  let(:service) { project.kubernetes_service }
+
+  # We use Kubeclient to interactive with the Kubernetes API. It will
+  # GET /api/v1 for a list of resources the API supports. This must be stubbed
+  # in addition to any other HTTP requests we expect it to perform.
+  let(:discovery_url) { service.api_url + '/api/v1' }
+  let(:discovery_response) { { body: kube_discovery_body.to_json } }
+
+  let(:pods_url) { service.api_url + "/api/v1/namespaces/#{service.namespace}/pods" }
+  let(:pods_response) { { body: kube_pods_body(kube_pod).to_json } }
+
+  def stub_kubeclient_discover
+    WebMock.stub_request(:get, discovery_url).to_return(discovery_response)
+  end
+
+  def stub_kubeclient_pods
+    stub_kubeclient_discover
+    WebMock.stub_request(:get, pods_url).to_return(pods_response)
+  end
 
   describe "Associations" do
     it { is_expected.to belong_to :project }
@@ -65,22 +87,15 @@ describe KubernetesService, models: true do
   end
 
   describe '#test' do
-    let(:project) { create(:kubernetes_project) }
-    let(:service) { project.kubernetes_service }
-    let(:discovery_url) { service.api_url + '/api/v1' }
-
-    # JSON response body from Kubernetes GET /api/v1 request
-    let(:discovery_response) { { "kind" => "APIResourceList", "groupVersion" => "v1", "resources" => [] }.to_json }
+    before do
+      stub_kubeclient_discover
+    end
 
     context 'with path prefix in api_url' do
       let(:discovery_url) { 'https://kubernetes.example.com/prefix/api/v1' }
 
-      before do
-        service.api_url = 'https://kubernetes.example.com/prefix/'
-      end
-
       it 'tests with the prefix' do
-        WebMock.stub_request(:get, discovery_url).to_return(body: discovery_response)
+        service.api_url = 'https://kubernetes.example.com/prefix/'
 
         expect(service.test[:success]).to be_truthy
         expect(WebMock).to have_requested(:get, discovery_url).once
@@ -88,17 +103,12 @@ describe KubernetesService, models: true do
     end
 
     context 'with custom CA certificate' do
-      let(:certificate) { "CA PEM DATA" }
-      before do
-        service.update_attributes!(ca_pem: certificate)
-      end
-
       it 'is added to the certificate store' do
-        cert = double("certificate")
+        service.ca_pem = "CA PEM DATA"
 
-        expect(OpenSSL::X509::Certificate).to receive(:new).with(certificate).and_return(cert)
+        cert = double("certificate")
+        expect(OpenSSL::X509::Certificate).to receive(:new).with(service.ca_pem).and_return(cert)
         expect_any_instance_of(OpenSSL::X509::Store).to receive(:add_cert).with(cert)
-        WebMock.stub_request(:get, discovery_url).to_return(body: discovery_response)
 
         expect(service.test[:success]).to be_truthy
         expect(WebMock).to have_requested(:get, discovery_url).once
@@ -107,17 +117,15 @@ describe KubernetesService, models: true do
 
     context 'success' do
       it 'reads the discovery endpoint' do
-        WebMock.stub_request(:get, discovery_url).to_return(body: discovery_response)
-
         expect(service.test[:success]).to be_truthy
         expect(WebMock).to have_requested(:get, discovery_url).once
       end
     end
 
     context 'failure' do
-      it 'fails to read the discovery endpoint' do
-        WebMock.stub_request(:get, discovery_url).to_return(status: 404)
+      let(:discovery_response) { { status: 404 } }
 
+      it 'fails to read the discovery endpoint' do
         expect(service.test[:success]).to be_falsy
         expect(WebMock).to have_requested(:get, discovery_url).once
       end
@@ -156,4 +164,55 @@ describe KubernetesService, models: true do
       )
     end
   end
+
+  describe '#terminals' do
+    let(:environment) { build(:environment, project: project, name: "env", slug: "env-000000") }
+    subject { service.terminals(environment) }
+
+    context 'with invalid pods' do
+      it 'returns no terminals' do
+        stub_reactive_cache(service, pods: [ { "bad" => "pod" } ])
+
+        is_expected.to be_empty
+      end
+    end
+
+    context 'with valid pods' do
+      let(:pod) { kube_pod(app: environment.slug) }
+      let(:terminals) { kube_terminals(service, pod) }
+
+      it 'returns terminals' do
+        stub_reactive_cache(service, pods: [ pod, pod, kube_pod(app: "should-be-filtered-out") ])
+
+        is_expected.to eq(terminals + terminals)
+      end
+    end
+  end
+
+  describe '#calculate_reactive_cache' do
+    before { stub_kubeclient_pods }
+    subject { service.calculate_reactive_cache }
+
+    context 'when service is inactive' do
+      before { service.active = false }
+
+      it { is_expected.to be_nil }
+    end
+
+    context 'when kubernetes responds with valid pods' do
+      it { is_expected.to eq(pods: [kube_pod]) }
+    end
+
+    context 'when kubernetes responds with 500' do
+      let(:pods_response) { { status: 500 } }
+
+      it { expect { subject }.to raise_error(KubeException) }
+    end
+
+    context 'when kubernetes responds with 404' do
+      let(:pods_response) { { status: 404 } }
+
+      it { is_expected.to eq(pods: []) }
+    end
+  end
 end

spec/support/kubernetes_helpers.rb

+module KubernetesHelpers
+  include Gitlab::Kubernetes
+
+  def kube_discovery_body
+    { "kind" => "APIResourceList",
+      "resources" => [
+        { "name" => "pods", "namespaced" => true, "kind" => "Pod" },
+      ],
+    }
+  end
+
+  def kube_pods_body(*pods)
+    { "kind" => "PodList",
+      "items" => [ kube_pod ],
+    }
+  end
+
+  # This is a partial response, it will have many more elements in reality but
+  # these are the ones we care about at the moment
+  def kube_pod(app: "valid-pod-label")
+    { "metadata" => {
+        "name" => "kube-pod",
+        "creationTimestamp" => "2016-11-25T19:55:19Z",
+        "labels" => { "app" => app },
+      },
+      "spec" => {
+        "containers" => [
+          { "name" => "container-0" },
+          { "name" => "container-1" },
+        ],
+      },
+      "status" => { "phase" => "Running" },
+    }
+  end
+
+  def kube_terminals(service, pod)
+    pod_name = pod['metadata']['name']
+    containers = pod['spec']['containers']
+
+    containers.map do |container|
+      terminal = {
+        selectors: { pod: pod_name, container: container['name'] },
+        url:  container_exec_url(service.api_url, service.namespace, pod_name, container['name']),
+        subprotocols: ['channel.k8s.io'],
+        headers: { 'Authorization' => ["Bearer #{service.token}"] },
+        created_at: DateTime.parse(pod['metadata']['creationTimestamp'])
+      }
+      terminal[:ca_pem] = service.ca_pem if service.ca_pem.present?
+      terminal
+    end
+  end
+end

spec/support/reactive_caching_helpers.rb

+module ReactiveCachingHelpers
+  def reactive_cache_key(subject, *qualifiers)
+    ([subject.class.reactive_cache_key.call(subject)].flatten + qualifiers).join(':')
+  end
+
+  def stub_reactive_cache(subject = nil, data = nil)
+    allow(ReactiveCachingWorker).to receive(:perform_async)
+    allow(ReactiveCachingWorker).to receive(:perform_in)
+    write_reactive_cache(subject, data) if data
+  end
+
+  def read_reactive_cache(subject)
+    Rails.cache.read(reactive_cache_key(subject))
+  end
+
+  def write_reactive_cache(subject, data)
+    start_reactive_cache_lifetime(subject)
+    Rails.cache.write(reactive_cache_key(subject), data)
+  end
+
+  def reactive_cache_alive?(subject)
+    Rails.cache.read(reactive_cache_key(subject, 'alive'))
+  end
+
+  def invalidate_reactive_cache(subject)
+    Rails.cache.delete(reactive_cache_key(subject, 'alive'))
+  end
+
+  def start_reactive_cache_lifetime(subject)
+    Rails.cache.write(reactive_cache_key(subject, 'alive'), true)
+  end
+
+  def expect_reactive_cache_update_queued(subject)
+    expect(ReactiveCachingWorker).
+      to receive(:perform_in).
+      with(subject.class.reactive_cache_refresh_interval, subject.class, subject.id)
+  end
+end

spec/workers/reactive_caching_worker_spec.rb

+require 'spec_helper'
+
+describe ReactiveCachingWorker do
+  let(:project) { create(:kubernetes_project) }
+  let(:service) { project.deployment_service }
+  subject { described_class.new.perform("KubernetesService", service.id) }
+
+  describe '#perform' do
+    it 'calls #exclusively_update_reactive_cache!' do
+      expect_any_instance_of(KubernetesService).to receive(:exclusively_update_reactive_cache!)
+
+      subject
+    end
+  end
+end

vendor/assets/javascripts/xterm/fit.js

+/*
+ *  Fit terminal columns and rows to the dimensions of its
+ *  DOM element.
+ *
+ *  Approach:
+ *    - Rows: Truncate the division of the terminal parent element height
+ *            by the terminal row height
+ *
+ *    - Columns: Truncate the division of the terminal parent element width by
+ *               the terminal character width (apply display: inline at the
+ *               terminal row and truncate its width with the current number
+ *               of columns)
+ */
+(function (fit) {
+  if (typeof exports === 'object' && typeof module === 'object') {
+    /*
+     * CommonJS environment
+     */
+    module.exports = fit(require('../../xterm'));
+  } else if (typeof define == 'function') {
+    /*
+     * Require.js is available
+     */
+    define(['../../xterm'], fit);
+  } else {
+    /*
+     * Plain browser environment
+     */
+    fit(window.Terminal);
+  }
+})(function (Xterm) {
+  /**
+   * This module provides methods for fitting a terminal's size to a parent container.
+   *
+   * @module xterm/addons/fit/fit
+   */
+  var exports = {};
+
+  exports.proposeGeometry = function (term) {
+    var parentElementStyle = window.getComputedStyle(term.element.parentElement),
+        parentElementHeight = parseInt(parentElementStyle.getPropertyValue('height')),
+        parentElementWidth = parseInt(parentElementStyle.getPropertyValue('width')),
+        elementStyle = window.getComputedStyle(term.element),
+        elementPaddingVer = parseInt(elementStyle.getPropertyValue('padding-top')) + parseInt(elementStyle.getPropertyValue('padding-bottom')),
+        elementPaddingHor = parseInt(elementStyle.getPropertyValue('padding-right')) + parseInt(elementStyle.getPropertyValue('padding-left')),
+        availableHeight = parentElementHeight - elementPaddingVer,
+        availableWidth = parentElementWidth - elementPaddingHor,
+        container = term.rowContainer,
+        subjectRow = term.rowContainer.firstElementChild,
+        contentBuffer = subjectRow.innerHTML,
+        characterHeight,
+        rows,
+        characterWidth,
+        cols,
+        geometry;
+
+    subjectRow.style.display = 'inline';
+    subjectRow.innerHTML = 'W'; // Common character for measuring width, although on monospace
+    characterWidth = subjectRow.getBoundingClientRect().width;
+    subjectRow.style.display = ''; // Revert style before calculating height, since they differ.
+    characterHeight = parseInt(subjectRow.offsetHeight);
+    subjectRow.innerHTML = contentBuffer;
+
+    rows = parseInt(availableHeight / characterHeight);
+    cols = parseInt(availableWidth / characterWidth) - 1;
+
+    geometry = {cols: cols, rows: rows};
+    return geometry;
+  };
+
+  exports.fit = function (term) {
+    var geometry = exports.proposeGeometry(term);
+
+    term.resize(geometry.cols, geometry.rows);
+  };
+
+  Xterm.prototype.proposeGeometry = function () {
+    return exports.proposeGeometry(this);
+  };
+
+  Xterm.prototype.fit = function () {
+    return exports.fit(this);
+  };
+
+  return exports;
+});