api+2.6

docs/api/api-examples.md

@@ -0,0 +1,228 @@
+# :fontawesome-solid-code: API
+
+Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You may also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API.
+
+!!! Note "API documentation is available [here](../api-schema/)"
+
+## :octicons-code-review-16: Examples
+
+!!! Note "The following examples use [httpie](https://httpie.org/){target=_blank} to execute API calls against Portainer"
+<br>
+### Initialize the admin password
+On a fresh install of Portainer, you need to create an admin account to initialize Portainer. You will be asked for this when you visit the Portainer url for the very first time. You can acheive the same using the below
+
+```shell 
+http POST <portainer url>/api/users/admin/init Username="<admin username>" Password="<adminpassword>"
+```
+<br>
+### Authenticate against the API using the admin account
+```shell
+http POST <portainer url>/api/auth Username="<admin username>" Password="<adminpassword>"
+```
+The response is a JSON object containing the JWT token inside the jwt field:
+```shell
+{
+  "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE"
+}
+```
+You need to retrieve this token. You will need to pass this token inside the Authorization header when executing an authentication query against the API.
+
+The value of the Authorization header must be of the form Bearer <JWT_TOKEN>.
+
+```
+Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE
+```
+
+**Note**: This token has a 8 hour validity, you'll need to generate another token to execute authenticated queries once this one expires.
+<br>
+### Create a new endpoint
+Here, We'll show how to create 3 different types of endpoints:
+
+* Local endpoint using Docker socket communication
+* Remote endpoint using TCP communication
+* Remote endpoint using TCP communication secured via TLS
+<br>
+#### Local endpoint via the Docker socket
+This query will create an endpoint called test-local and will use the Docker socket to communicate with this environment.
+
+**Note**: This example requires to you bind-mount the Docker socket when running Portainer.
+
+```shell
+http --form POST <portainer url/api/endpoints \
+"Authorization: Bearer <jwt token>" \
+Name="<endpoint name>" EndpointCreationType=1
+```
+The response is a JSON object representing the endpoint:
+
+```json
+{
+    "AuthorizedTeams": [], 
+    "AuthorizedUsers": [], 
+    "Extensions": [], 
+    "GroupId": 1, 
+    "Id": 2, 
+    "Name": "<endpoint name>", 
+    "PublicURL": "",
+    "Type": 1,
+    "TLSConfig": {
+        "TLS": false, 
+        "TLSSkipVerify": false
+    }, 
+    "Type": 1, 
+    "URL": "unix:///var/run/docker.sock"
+}
+```
+<br>
+#### Remote endpoint
+This query will create an endpoint called test-remote and will communicate with this environment over TCP using the IP address 10.0.7.10 and port 2375 (these are example values, ensure that you're using the correct IP & port).
+
+**Note**: The Docker API must be exposed on that IP address & port. Please refer to the Docker documentation to check how to configure this.
+
+```shell
+http --form POST <portainer url>/api/endpoints \
+"Authorization: Bearer <jwt token>" \
+Name="test-remote" URL="tcp://10.0.7.10:2375" EndpointCreationType=1
+```
+The response is a JSON object representing the endpoint:
+
+```json
+{
+    "AuthorizedTeams": [], 
+    "AuthorizedUsers": [], 
+    "Extensions": [], 
+    "GroupId": 1, 
+    "Id": 1, 
+    "Type": 1,
+    "Name": "test-remote", 
+    "PublicURL": "", 
+    "TLSConfig": {
+        "TLS": false, 
+        "TLSSkipVerify": false
+    }, 
+    "Type": 1, 
+    "URL": "tcp://10.0.7.10:2375"
+}
+```
+<br>
+#### Remote endpoint secured using TLS
+
+This query will create an endpoint called test-remote-tls and will communicate with this environment over TCP (secured with TLS) using the IP address 10.0.7.10 and port 2376 (these are example values, ensure that you're using the correct IP & port).
+
+**Note**: The Docker API must be exposed on that IP address & port. Please refer to the Docker documentation to check how to configure this.
+
+```shell
+http --form POST <portainer url>/api/endpoints \
+"Authorization: Bearer <jwt token>" \
+Name="test-remote-tls" URL="tcp://10.0.7.10:2376" EndpointCreationType=1 TLS="true" TLSCACertFile@/path/to/ca.pem TLSCertFile@/path/to/cert.pem TLSKeyFile@/path/to/key.pem
+```
+The response is a JSON object representing the endpoint:
+
+```json
+{
+    "AuthorizedTeams": [], 
+    "AuthorizedUsers": [], 
+    "Extensions": [], 
+    "GroupId": 1, 
+    "Id": 1, 
+    "Type": 1,
+    "Name": "test-remote", 
+    "PublicURL": "", 
+    "TLSConfig": {
+        "TLS": true, 
+        "TLSCACert": "/data/tls/1/ca.pem", 
+        "TLSCert": "/data/tls/1/cert.pem", 
+        "TLSKey": "/data/tls/1/key.pem", 
+        "TLSSkipVerify": false
+    }, 
+    "Type": 1, 
+    "URL": "tcp://10.0.7.10:2376"
+}
+```
+<br>
+### Execute Docker queries against a specific endpoint
+
+By using the following Portainer HTTP API endpoint /api/endpoints/<ENDPOINT_ID>/docker, you can now execute any of the Docker HTTP API requests.
+
+This Portainer HTTP API endpoint acts as a reverse-proxy to the Docker HTTP API.
+
+**Note**: You can refer to the Docker API [documentation](https://docs.docker.com/engine/api/) to get more information on how you can query the Docker engine.
+
+<br>
+
+#### List all containers
+
+Here is how you can list all the containers available in a specific endpoint:
+
+```shell
+http GET <portainer url>/api/endpoints/1/docker/containers/json \
+"Authorization: Bearer <jwt token>" \
+all==true
+```
+The response is exactly the same as returned by the ContainerList operation of the Docker API, see the [documentation for the ContainerList operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerList){target=_blank}.
+
+<br>
+
+#### Create a container
+
+Here is how you can create a container in a specific endpoint using the Portainer HTTP API as a gateway.
+
+This query will create a new Docker container inside the endpoint using the ID 1. The container will be named web01, use the nginx:latest Docker image and publish the container port 80 on via the 8080 port on the host.
+
+See the link below to retrieve more information on how you can create a container using the Docker HTTP API.
+
+```shell
+http POST <portainer url>/api/endpoints/1/docker/containers/create \
+"Authorization: Bearer <jwt token>" \
+name=="web01" Image="nginx:latest" \
+ExposedPorts:='{ "80/tcp": {} }' \
+HostConfig:='{ "PortBindings": { "80/tcp": [{ "HostPort": "8080" }] } }'
+```
+
+The response is exactly the same as returned by the ContainerCreate operation of the Docker API, see the [documentation for the ContainerCreate operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerCreate){target=_blank}.
+
+Example response:
+
+```json
+{
+    "Id": "5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107",
+    "Warnings": null
+}
+```
+
+Retrieve the ID of the container, you will need it to execute actions against that container.
+
+<br>
+
+#### Start a container
+
+You can now start the container that you previously created using the endpoint /api/endpoints/<ENDPOINT_ID>/docker/containers/<CONTAINER_ID>/start (ensure you retrieved the ID of the container created previsouly):
+
+```shell
+http POST <portainer url>/api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107/start \
+"Authorization: Bearer <jwt token>"
+```
+
+The response is exactly the same as returned by the ContainerStart operation of the Docker API, see the [documentation for the ContainerStart operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerStart){target=_blank}.
+
+<br>
+
+#### Delete a container
+
+You can create a container using the following endpoint /api/endpoints/<ENDPOINT_ID>/docker/containers/<CONTAINER_ID>:
+
+```shell
+http DELETE <portainer url>/api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107 \
+"Authorization: <jwt token>" \
+force==true
+```
+
+The response is exactly the same as returned by the ContainerDelete operation of the Docker API, see the [documentation for the ContainerDelete operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerDelete){target=_blank}.
+
+<br>
+<br>
+*More Examples to be added soon*
+<br>
+
+## :material-note-text: Notes
+
+[Contribute to these docs](https://github.com/portainer/portainer-docs/blob/master/contributing.md){target=_blank}

docs/v2.0/auth/oauth.md

@@ -1,6 +1,6 @@
 # OAuth authentication
 
-Portainer allows that the authentication can be done with OAuth and with this help article, you will see a overview of what's the requirement to configure Portainer CE 2.0 with OAuth. 
+Portainer allows that the authentication can be done with OAuth and with this help article, you will see a overview of what's the requirement to configure Portainer CE with OAuth. 
 
 ## Start to configure OAuth authentication in Portainer
 
@@ -8,18 +8,20 @@ Once you logged to Portainer, click in <b>Settings</b> and then in <b>authentica
 
 ![oauth](assets/oauth_1.png)
 
-In this screen, you need to configure the data that you OAuth provider give you to configure Portainer. The fields are:
+In this screen, you need to fill in the details using the details provided by your OAuth provider. The fields are:
 
-* Automatic User Provisioning: Toggle on the                       se options if you want to create users for each user logged using OAuth. After enable the toggle, you need to define in wich team that users should be created. 
+* Use SSO: Using SSO, the OAuth provider is not forced to prompt for credentials when the user has a currently logged in session.
+* Automatic User Provisioning: Toggle on the Automatic User Provisioning to see the options. You can use this option if you want a user added to Portainer for each OAuth useron first login. After enabling the toggle, you may choose a team for these Auto Populated Users. 
 
 ![oauth](assets/oauth_2.png)
 
 * Client ID: This is the public identifier of the OAuth application.
 * Client Secret: Here, you need to fill with the token access to the OAuth Application.
 * Authorization URL: URL used to authenticate against the OAuth provider. Will redirect the user to the OAuth provider login view.
-* Access Token URL: URL used to authenticate against the OAuth provider. Will redirect the user to the OAuth provider login view.
+* Access Token URL: URL used to exchange a valid OAuth authentication code for an access token.
 * Resource URL: URL used by Portainer to retrieve information about the authenticated user.
 * Redirect URL: URL used by the OAuth provider to redirect the user after successful authentication. Should be set to your Portainer instance URL.
+* Logout URL: URL used by the OAuth provider to logout the user. 
 * User Identifier: Identifier that will be used by Portainer to create an account for the authenticated user. Retrieved from the resource server specified via the Resource URL field.
 * Scopes: Required by the OAuth provider to retrieve information about the authenticated user. Refer to your OAuth provider documentation for more information about this.
 

docs/v2.0/kubernetes/applications/create.md

@@ -16,7 +16,7 @@ After that, you will see a form to complete according to your needs. The options
 
 * Name: Name of your Container.
 * Image: This is the image you want to use to deploy your container.
-* Resource Pool: This is the namespace where your container is going to live. To add a new resource pool, see this [help article](/v2.0/docs/kubernetes/resouce_pool/create.md).
+* Namespace/Resource Pool: This is the namespace where your container is going to live. To add a new Namespace/Resource Pool, see this [help article](/v2.0/docs/kubernetes/resouce_pool/create.md).
 * Stack: Portainer can automatically bundle multiple applications inside a stack. Enter a name of a new stack or select an existing stack in the list. Leave empty to use the application name.
 * Environment Variables: Fill the environment that your app needs, this is optional and only depends of the configuration supported by your app.
 * Configurations: If you created configuration files before using Portainer, you can select that configuration in this space.

docs/v2.0/kubernetes/applications/inspect.md

@@ -11,7 +11,7 @@ In the tab <b>Application</b>, you can find the following information:
 
 * Name: Name of the application.
 * Stack: Name of the stack that this container belongs.
-* Resource Pool: In what resouce pool / Namespace this application in running.
+* Namespace/Resource Pool: In what resouce pool / Namespace this application in running.
 * Application Type.
 * Status: See if the application is running.
 * Creation: Information about who and when the application was created.

docs/v2.0/kubernetes/applications/manifest.md

@@ -8,9 +8,25 @@ In Portainer you can launch new applications using your current manifest in YML
 
 To start, click <b>Applications</b> and then <b>Advanced Deployment</b>.
 
+Here you have the option to use a manifest file that is in a git repo or enter the YAML manifest using the web editor.
+
+### Manifest from git
+
 ![manifest](assets/manifest-1.png)
 
-In this section, you need to define the resource pool where your applications are going to be deployed and start to write or paste your Kubernetes Manifest. Once this is done, click <b>Deploy</b>.
+Select the Namespace to deploy the application to, Select Kubernetes or Compose based on the format of your manifest. Select **Git Repository**, enter the details for your git repo. Toggle on and enter Authentication details if required for the repo. Finally, Click **Deploy**.
+
+![manifest](assets/manifest-git.png)
+
+If everything works as expected you will see this pop up:
+
+![manifest](assets/manifest-3.png)
+
+### Manifest using Web editor
+
+![manifest](assets/manifest-1.png)
+
+In this section, you need to define the Namespace/Resource Pool where your applications are going to be deployed and start to write or paste your Kubernetes Manifest. Once this is done, click <b>Deploy</b>.
 
 ![manifest](assets/manifest-2.png)
 

docs/v2.0/kubernetes/configurations/create.md

@@ -11,7 +11,7 @@ To create a configuration, click <b>Configurations</b> and then click <b>Add con
 In the next screen, you need to define the following:
 
 * Name: Name your configuration.
-* Resource Pool: Where the configuration is going to be saved.
+* Namespace/Resource Pool: Where the configuration is going to be saved.
 * Configuration Type:
   - Non-sensitive: This configuration holds non-sensitive information.
   - Sensitive: This configuration holds sensitive information like passwords or certificates

docs/v2.0/kubernetes/resource_pools/access.md

@@ -1,4 +1,4 @@
-# Manage access to a resource pool
+# Manage access to a Namespace/Resource Pool
 
 !!! Warning "Access Control & RBAC"
     Kubernetres RBAC needs to enabled and working for Access Control to work properly in Portainer.
@@ -7,7 +7,7 @@ In this help article, you will learn how to manage access to created resource po
 
 ## Managing access
 
-Click <b>Resource Pools</b> then click <b>Manage Access</b> of the resource pool you want.
+Click <b>Namespaces/Resource Pools</b> then click <b>Manage Access</b> of the Namespace/Resource Pool you want.
 
 ![access](assets/access-1.png)
 

docs/v2.0/kubernetes/resource_pools/create.md

@@ -1,14 +1,17 @@
-# Create a Resource Pool
+???+ Hint ""
+    From Portainer CE 2.6 on, `Resource Pool(s)` has been renamed to `Namespace(s)` to be aligned with Kubernetes lingo.
 
-The Resource Pools are helpful when multiple teams are using the same cluster and there is potential collision, you can prevent this by using a virtual wall between multiple clusters. In this help article, you will learn how to create a Resource Pool (Namespace) using Portainer.
+# Create a Namespace/Resource Pool
 
-## Creating a Resouce Pool
+The Namespaces/Resource Pools are helpful when multiple teams are using the same cluster and there is potential collision, you can prevent this by using a virtual wall between multiple clusters. In this help article, you will learn how to create a Namespace/Resource Pool using Portainer.
 
-Go to <b>Resouce Pools</b> and then click <b>Add resource pool</b>.
+## Creating a Namespace/Resource Pool
+
+Go to <b>Namespaces/Resource Pools</b> and then click <b>Add Namespace/Resource pool</b>.
 
 ![resource_pool](assets/create-1.png)
 
-In the next screen, you need to <b>name</b> your resource pool, assign a <b>quota<b> (Optional), set the <b>resource limits</b> of that quota indicating how much memory and CPU is assigned to this Resource Pool.
+In the next screen, you need to <b>name</b> your resource pool, assign a <b>quota<b> (Optional), set the <b>resource limits</b> of that quota indicating how much memory and CPU is assigned to this Namespace/Resource Pool.
 
 When everything is set, click <b>Create resource pool</b>.
 

docs/v2.0/kubernetes/resource_pools/delete.md

@@ -1,10 +1,10 @@
-# Delete/Remove a Resource Pool
+# Delete/Remove a Namespace/Resource Pool
 
 When you have finished your project, you can delete resource pools to free up resources.
 
-## Removing a Resouce Pool
+## Removing a Namespace/Resource Pool
 
-Click <b>Resouce Pools</b>, select the resource pool and click <b>Remove</b>.
+Click <b>Namespace/Resouce Pools</b>, select the Namespace/Resource pool and click <b>Remove</b>.
 
 ![resource](assets/delete-1.png)
 

mkdocs.yml

@@ -175,9 +175,9 @@ nav:
             - 'Delete an Application' : 'v2.0/kubernetes/applications/delete.md'
             - 'Inspect an Application' : 'v2.0/kubernetes/applications/inspect.md'
           - 'Resource Pools':
-            - 'Create a Resource Pool' : 'v2.0/kubernetes/resource_pools/create.md'
+            - 'Create a Namespace/Resource Pool' : 'v2.0/kubernetes/resource_pools/create.md'
             - 'Manage Access' : 'v2.0/kubernetes/resource_pools/access.md'
-            - 'Delete a Resource Pool' : 'v2.0/kubernetes/resource_pools/delete.md'
+            - 'Delete a Namespace/Resource Pool' : 'v2.0/kubernetes/resource_pools/delete.md'
           - 'Volumes':
             - 'Inspect a volume' : 'v2.0/kubernetes/volumes/inspect.md'
             - 'Resize a volume' : 'v2.0/kubernetes/volumes/resize.md'
@@ -275,7 +275,9 @@ nav:
         - Registries:
           - 'Browse a Registry' : 'v2.0-be/registries/browse.md'
           - 'Manage a Registry' : 'v2.0-be/registries/manage.md'        
-    - API: api.md
+    - API: 
+      - 'Documentation': 'api/api-schema.md'
+      - 'Examples': 'api/api-examples.md'
     - Upgrading Portainer:
       - 'Upgrade Path': 'upgrade.md'
       - 'Upgrade CE to Business': 'v2.0/upgrade/updBE.md'
@@ -346,6 +348,7 @@ plugins:
             'v2.0-be/deploy/linux.md': 'quickstart.md'
             'v2.0-be/deploy/windows10.md': 'quickstart.md'
             'v2.0-be/deploy/windowsserver.md': 'quickstart.md'
+            'api.md': 'api/api-examples.md'
 
 extra:
   analytics: