blob: df24cff4c05b63821e449c8a899e7c165bab65d5 [file] [log] [blame]
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="stylesheet" href="/packages/assets/bootstrap/bootstrap.min.css">
<title>Pre-Requisites</title>
<link rel="stylesheet" href="/packages/assets/css/style.css">
<script src="/packages/assets/js/code.js"></script>
<meta name="twitter:card" content="summary"/>
<meta name="twitter:image" content="https://staging.eclipse.org/packages/images/icon/twitter_icon.png"/>
<meta name="twitter:title" content="Pre-Requisites"/>
<meta name="twitter:description" content=""/>
<link rel="icon" type="image/svg+xml" href="/packages/images/icon/icon.svg" sizes="any">
<link rel="icon" href="/packages/images/icon/icon.png" sizes="192x192">
<link rel="apple-touch-icon-precomposed" href="/packages/images/icon/icon_apple.png" sizes="180x180">
</head>
<body>
<header>
<nav class="navbar navbar-expand-md fixed-top navbar-light bg-light">
<div class="container">
<a class="navbar-brand" href="/packages/">
<img src="/packages/images/icon_brand_navbar.svg" width="30" height="30" alt="Eclipse IoT Packages™">
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarCollapse">
<ul class="navbar-nav mr-auto"><li class="nav-item">
<a
class="nav-link"
href="/packages/">Home</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/about/">About</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/faq/">FAQ</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/contribute/">Contribute</a>
</li>
<li class="nav-item">
<a
class="nav-link active"
href="/packages/prereqs/">Prerequisites</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/repository/">Repository</a>
</li>
</ul>
</div>
</div>
</nav></header>
<main id="main" role="main" >
<div class="container mt-5">
<h1>Pre-Requisites</h1>
<p class="lead">Getting you started with a common set of tools, used by all packages.</p>
</div>
<div class="container">
<div class="row">
<div class="col-12 col-md-8 col-lg-9">
<h2 id="kubernetes-client">Kubernetes Client</h2>
<p>First of all, you will need a command tool named <code class="highlighter-rouge">kubectl</code>. This application allows you to interact with
your Kubernetes cluster from the command line. While Kubernetes also comes with a Web UI, it is much simpler
to document the installation procedures using command line tool. Also does the Web UI change over time, and
with different Kubernetes variants. However the <code class="highlighter-rouge">kubectl</code> tool works with all variations of Kubernetes, as it
uses the standardized API in the background.</p>
<p>You can find more information in the Kubernetes documentation: <a href="https://kubernetes.io/docs/tasks/tools/install-kubectl/">Install and Set Up kubectl</a>.</p>
<h2 id="kubernetes-cluster">Kubernetes Cluster</h2>
<p>For the cloud side environment, you will need an installation of Kubernetes. Kubernetes comes in
different forms, and we try to document a few of them for you. There are other variants as well,
and you are welcome to try all of them. All packages should be able to run on any Kubernetes
you provide.</p>
<p>Packages are encouraged to give you an estimate of what resources they require. The following is
an example of what this may look like. You will need to translate this into the specific
Kubernetes environment you have. Also may the package declare on which Kubernetes platform
it was tested. This doesn’t mean that other Kubernetes versions don’t work, but sets some
expectations of what was tested at some point.</p>
<div class="row">
<div class="col-12 col-sm-6 col-md-5 col-lg-4 mx-md-auto mb-3">
<div class="card req-card">
<div class="card-header text-center"><h5>Requirements</h5></div>
<ul class="list-group list-group-flush">
<li class="list-group-item">
<dl class="row">
<dt class="col-sm-6">Kubernetes</dt>
<dd class="col-sm-6 text-right">1.15.x</dd>
</dl>
</li>
<li class="list-group-item">
<dl class="row">
<dt class="col-sm-6">CPUs</dt>
<dd class="col-sm-6 text-right">2</dd>
</dl>
</li>
<li class="list-group-item">
<dl class="row">
<dt class="col-sm-6">Memory</dt>
<dd class="col-sm-6 text-right">1024 MiB</dd>
</dl>
</li>
<li class="list-group-item">
<dl class="row">
<dt class="col-sm-6">Disk</dt>
<dd class="col-sm-6 text-right">40 GiB</dd>
</dl>
</li>
</ul>
<div class="card-body">Additional requirements.</div>
</div>
</div>
</div>
<p>For each documentation Kubernetes environment on this page, you will
find a section that explains how to do this.</p>
<h3 id="minikube">Minikube</h3>
<p><a href="https://kubernetes.io/docs/setup/learning-environment/minikube/">Minikube</a> is Kubernetes in a bottle.</p>
<p>Instead of provisioning a full blown cluster, it will create a virtual machine on your local system, and
provision a small, single-node cluster inside of it. As it puts the operating system in a VM, Minikube itself
can run on all major operating systems, including Windows and Mac OS.</p>
<p>Instead of duplicating the effort, documenting how to get Minikube up an running, we leave this to the
excellent <a href="https://kubernetes.io/docs/tasks/tools/install-minikube/">documentation of Minikube</a> itself.</p>
<h4 id="getting-started">Getting started</h4>
<p>Once you have everything installed, you should be able to start a new cluster by executing:</p>
<div class="clipboard"><pre><code>minikube start</code></pre></div>
<p>And you can switch <code class="highlighter-rouge">kubectl</code> to the context <code class="highlighter-rouge">minikube</code>, and interact with your cluster:</p>
<div class="clipboard"><pre><code>kubectl config use-context minikube</code></pre></div>
<p>For example, get the current version of the client and server:</p>
<div class="clipboard"><pre><code>kubectl version</code></pre></div>
<p>Which should show a proper version for the client <strong>and</strong> the server:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Client Version: version.Info{Major:"1", Minor:"11+", GitVersion:"v1.11.0+d4cacc0", GitCommit:"d4cacc0", GitTreeState:"clean", BuildDate:"2018-10-10T16:38:01Z", GoVersion:"go1.10.3", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"13+", GitVersion:"v1.13.4+c2a5caf", GitCommit:"c2a5caf", GitTreeState:"clean", BuildDate:"2019-09-21T02:12:52Z", GoVersion:"go1.11.13", Compiler:"gc", Platform:"linux/amd64"}
</code></pre></div> </div>
<h4 id="starting-and-stopping">Starting and stopping</h4>
<p>When you no longer need your cluster, you can stop it using:</p>
<div class="clipboard"><pre><code>minikube stop</code></pre></div>
<p>This will suspend the VM so that you can, later on, resume it by
executing:</p>
<div class="clipboard"><pre><code>minikube start</code></pre></div>
<p>Or delete it using:</p>
<div class="clipboard"><pre><code>minikube delete</code></pre></div>
<h4 id="resources">Resources</h4>
<p>You can translate the package resources requirements into arguments for the <code class="highlighter-rouge">start</code> command like this:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>minikube start --cpus &lt;cpus&gt; --disk-size &lt;size&gt; --memory &lt;memory&gt; --kubernetes-version &lt;version&gt;
</code></pre></div> </div>
<p>Using the following arguments:</p>
<dl class="row">
<dt class="col-sm-2">cpus</dt>
<dd class="col-sm-10">The number of CPUs you allocate for Minikube (e.g. <code>--cpus 2</code>).</dd>
<dt class="col-sm-2">size</dt>
<dd class="col-sm-10">
The size of the disk available for the cluster and persistent volumes. In the format <code>&lt;number&gt;&lt;unit&gt;</code>,
where unit can be either <code>k</code>, <code>m</code>, or <code>g</code> (e.g. 20GiB means <code>--disk-size 20g</code>).
</dd>
<dt class="col-sm-2">memory</dt>
<dd class="col-sm-10">
The amount of RAM allocated to the virtual machine. This is the amount in MiB (e.g. for 8GiB means <code>--memory 8192</code>.
</dd>
<dt class="col-sm-2">version</dt>
<dd class="col-sm-10">
The Kubernetes version deployed into the virtual machine (e.g. <code>--kubernetes-version v1.15.4</code>).
</dd>
</dl>
<h2 id="helm">Helm</h2>
<p>You will need an installation of Helm on the machine which is used to deploy the packages. You can find
installation instructions for Helm in the Helm documentation under <a href="https://helm.sh/docs/using_helm/#installing-helm">Installing Helm</a>.</p>
<h3 id="repository">Repository</h3>
<p>The Eclipse IoT Packages projects publishes a Helm chart repository for Eclipse IoT projects.</p>
<p>Adding the repository can be done on your local machine be executing:</p>
<div class="clipboard"><pre><code>helm repo add eclipse-iot https://eclipse.org/packages/charts</code></pre></div>
<p>Read more: <a href="/packages/repository" title="title">Helm chart repository</a>.</p>
<h3 id="version-2-and-3">Version 2 and 3</h3>
<p>As of now, we support both Helm 2 and 3. As version 3 can also process version 2 charts, this isn’t a problem.</p>
<p>We will consider switching to Helm 3 only at a later time.</p>
<h3 id="tiller">Tiller</h3>
<p>You will not need to install Tiller on the cluster. Of course, if you prefer to use Tiller, you may still
do so. Also see: <a href="/packages/faq/#why-aren-t-you-using-tiller">FAQ: Why aren’t you using Tiller</a>.</p>
<h2 id="command-line-tools">Command line tools</h2>
<p>Some tutorials might require some common command line tool. The installation depends on the
operating system you are using.</p>
<p>It is required to have the following tools installed:</p>
<h3 id="bash">Bash</h3>
<p>Bash is available on Windows, Linux and Mac OS X. True platform independence. So all commands which
you are supposed to execute can be executed in Bash, version 3 or newer.</p>
<h3 id="curl">curl</h3>
<p>For downloading files and execution API call the tool <code class="highlighter-rouge">curl</code> will be used.</p>
<h3 id="mosquitto-cli">Mosquitto CLI</h3>
<p>Mosquitto command line tools: e.g. <code class="highlighter-rouge">moquitto_pub</code></p>
</div>
<div class="col-12 col-md-4 col-lg-3
">
<div class="position-sticky" style="top: 4rem;">
<aside>
<div class="card">
<div class="card-body">
<h5 class="card-title">Table of contents</h5>
<div id="toc" class="toc"></div>
</div>
</div>
</aside>
<script>generateToc("#toc", "h2[id], h3[id], h4[id]");</script>
</div>
</div>
</div>
</div>
</main>
<footer>
<div class="container">
<div class="row">
<div class="col-6 col-md">
<h5>Eclipse IoT Packages</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="/packages/">Home</a>
</li>
<li>
<a class="text-muted" href="/packages/about">About</a>
</li>
<li>
<a class="text-muted" href="/packages/contribute">Contribute</a>
</li>
<li>
<a class="text-muted" href="https://eclipse.org/security">Security</a>
</li>
</ul>
</div>
<div class="col-6 col-md">
<h5>Eclipse IoT</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="https://iot.eclipse.org">Top Level Project</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/org/workinggroups/iotwg_charter.php">Working group</a>
</li>
</ul>
</div>
<div class="col-6 col-md">
<h5>Legal</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a>
</li>
<li>
<a class="text-muted" href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/legal/epl-2.0/">Eclipse Public License</a>
</li>
<li>
<a class="text-muted" href="http://www.eclipse.org/legal">Legal Resources</a>
</li>
</ul>
</div>
<div class="col-6 col-md">
<h5>Eclipse Foundation</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="https://eclipse.org/org">About us</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/org/foundation/contact.php">Contact us</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/org/foundation/directors.php">Board of Directors</a>
</li>
</ul>
</div>
</div>
<div class="row">
<div class="col-12 col-md text-muted">Copyright © Eclipse Foundation, Inc. All Rights Reserved.</div>
</div>
</div>
</footer>
<script src="/packages/assets/popper.min.js"></script>
<script src="/packages/assets/jquery.min.js"></script>
<script src="/packages/assets/bootstrap/bootstrap.min.js"></script>
<script src="/packages/assets/clipboard.min.js"></script>
<script src="/packages/assets/clipboard.js"></script>
</body>
</html>