Docs

docs/auth/overview.md

@@ -1,6 +1,6 @@
 ---
 title: Authentication & Authorization
-sidebar_label: Overview
+sidebar_label: Auth Overview
 ---
 
 Kalm has built in systems for managing user **Authentication** and **Authorization**. The following documentation provides a high level overview of how Kalm's Auth systems work.
@@ -47,4 +47,3 @@ For specific details on Kalm's Role Permission definitions, see our [detailed Ro
 The Kubernetes RBAC is powerful and configurable for teams which require precise control at a granular level. However, it can be quite complicated for simple scenarios involving standard permissions and roles. This complexity grows proportionately to the number of CRDs involved.
 
 Kalm's RBAC system is designed to be initially simple and intuitive, while still allowing for complex customization if needed.
-

docs/cert-challenge.md

@@ -1,16 +1,18 @@
 ---
-title: Certificate Issuing
+lastAuthor: infrar
+lastEdited: 1611360652055
 ---
-
 ## Overview
 
 Kalm can help you create certificates via Let's Encrypt. This article provides an overview of how certificates are obtained, including extra details on complexities regarding issuance and renewal of **wildcard** certificates.
 
+\
+Adding some content.
+
 ## Obtaining a (non-wildcard) certificate
 
 When requesting a certificate from Let's Encrypt, you must complete a "challenge" to prove that you are in control of the domain(s) to be certified. There are multiple types of challenges. Typically we can just use **HTTP-01**, which is the most common and simplest challenge type.
 
-
 ### HTTP-01
 
 Let's Encrypt generates a random token, which you must serve at a specific url:
@@ -25,9 +27,9 @@ This proves that you have permission to serve files(and are therefore in control
 
 Kalm automates most of this process, all you have to do is point <YOUR_DOMAIN> to the IP of the Kalm cluster. For example, if <YOUR_DOMAIN> is **myapp.com** and the cluster IP is **34.84.45.1**, you would add the following DNS record.
 
-| Type | Host      | Answer    |
-| ---- | --------- | ---------- |
-| A    | myapp.com | 34.84.45.1 |
+| Type | Host | Answer |
+|----|----|----|
+| A | myapp.com | 34.84.45.1 |
 
 Then you can initiate the certificate obtaining process in the Kalm UI by following [this guide](https-certs). Behind the scenes, Kalm does the necessary work to ensure that the token is accessible via the specified URL, then tells Let's Encrypt to initiate the challenge.
 
@@ -41,9 +43,9 @@ Instead of serving a token on your webserver, the DNS-01 challenge asks you to p
 
 To complete the challenge, you could manually add an entry to your DNS provider:
 
-| Type | Host                       | Answer        |
-| ---- | -------------------------- | -------------- |
-| TXT  | \_acme-challenge.myapp.com | <RANDOM_TOKEN> |
+| Type | Host | Answer |
+|----|----|----|
+| TXT | _acme-challenge.myapp.com | <RANDOM_TOKEN> |
 
 However, depending on your DNS provider's API you may not be able to **automatically renew** this certificate. Instead a common solution is to delegate the DNS lookup to a **Validation-specific DNS Server**. Kalm provides a validation-specific DNS Server out of the box for this exact usecase.
 
@@ -57,10 +59,10 @@ acme-d985e9.mycluster.com
 
 The Validation-specific DNS Server contains 2 entries created by default.
 
-| Type | Host                         | Answer                      |
-| ---- | ---------------------------- | ---------------------------- |
-| A    | ns.acme-d985e9.mycluster.com | 34.84.45.105                 |
-| NS   | acme-d985e9.mycluster.com    | ns.acme-d985e9.mycluster.com |
+| Type | Host | Answer |
+|----|----|----|
+| A | ns.acme-d985e9.mycluster.com | 34.84.45.105 |
+| NS | acme-d985e9.mycluster.com | ns.acme-d985e9.mycluster.com |
 
 The A record indicates that there is a DNS server ns.acme-d985e9.mycluster.com located at 34.84.45.105.
 
@@ -78,21 +80,21 @@ Let's say we want to obtain a wildcard certificate for:
 
 We can create a new certificate in Kalm. At this point, Kalm will generate a unique challenge URL that is capable of passing the DNS-01 challenge. The challenge URL is shown in the Certificate details page:
 
-![pic with domain for wildcard cert](./assets/wildcard-cname-cert.png)
+ ![pic with domain for wildcard cert](./assets/wildcard-cname-cert.png)
 
 This table indicates that the challenge for **\*.myapp.com** can be answered by **b6e4682c-5109-4a34-ac99-d5097d5b2b68.acme.mycluster.com**.
 
 Thus, in order to create a wildcard certificate for myapp.com, all we need to do is add a CNAME record at the DNS provider of myapp.com
 
-| Type  | Host                           | Answer                                                  |
-| ----- | ------------------------------ | ------------------------------------------------------- |
-| CNAME | **\_acme-challenge.myapp.com** | b6e4682c-5109-4a34-ac99-d5097d5b2b68.acme.mycluster.com |
+| Type | Host | Answer |
+|----|----|----|
+| CNAME | **_acme-challenge.myapp.com** | b6e4682c-5109-4a34-ac99-d5097d5b2b68.acme.mycluster.com |
 
-_*Note - some DNS management interfaces automatically include your domain (".myapp.com" in the above example) at the end of the Host. In this case, only include the first portion of the Host and omit the rest of the domain (Host = "\_acme-challenge")_
+*\*Note - some DNS management interfaces automatically include your domain (".myapp.com" in the above example) at the end of the Host. In this case, only include the first portion of the Host and omit the rest of the domain (Host = "_acme-challenge")*
 
 From this point on, Kalm tells Let's Encrypt to initiate the challenge. The following steps occur:
 
-1. Let's encrypt will make a request to **\_acme-challenge.myapp.com**
+1. Let's encrypt will make a request to **_acme-challenge.myapp.com**
 2. The request gets forwarded to **b6e4682c-5109-4a34-ac99-d5097d5b2b68.acme.mycluster.com** due to the CNAME record
 3. The TXT record for **b6e4682c-5109-4a34-ac99-d5097d5b2b68.acme.mycluster.com** is the secret token (served by the Validation-specific DNS server)
 4. The challenge passes and the certification process proceeds normally.
@@ -103,6 +105,6 @@ As long as the CNAME record at your DNS provider is kept intact, the path will w
 
 #### Wildcard Cert Issuing Flow
 
-![](./assets/acme-dns-flow.svg)
+ ![](./assets/acme-dns-flow.svg)
 
-_Note: This flowchart is hard to follow, should redraw a simpler version with bigger text._
+*Note: This flowchart is hard to follow, should redraw a simpler version with bigger text.*

docs/crd/access-token.mdx

@@ -2,30 +2,50 @@
 title: Access Token
 ---
 
+`AccessToken` defines a token with permissions.
+
+For example, the following configurations sets up a token with edit permission for the component named `wordpress` in the default namespace:
+
+```yaml
+apiVersion: core.kalm.dev/v1alpha1
+kind: AccessToken
+metadata:
+  name: c153f45fd4344...95d29ec2a3bad2d8
+spec:
+  creator: [email protected]
+  memo: token for update webhook
+  rules:
+    - kind: components
+      name: wordpress
+      namespace: default
+      verb: edit
+  token: 4ddb864cfx56pkxw
+```
+
 ## AccessToken
 
-A model to describe general access token permissions, It's designed to be easy to translate to [casbin](https://casbin.org/) policies. 
+A model to describe general access token permissions, It's designed to be easy to translate to [casbin](https://casbin.org/) policies.
 
 This model should NOT be generate manually through Kubernetes api directly. Instead, use kalm apis to manage records.
 
-| Name      | Type                                                         | Description                        | Required |
-| --------- | ------------------------------------------------------------ | ---------------------------------- | -------- |
-| memo      | string                                                       | memo for this token                | False    |
-| token     | string                                                       | token value, minimum length is 64  | True     |
-| rules     | [AccessTokenRule](#accesstokenrule)[]                        | rules of this token                | True     |
-| creator   | string                                                       | creator of this token              | True     |
-| expiredAt | *[metav1.Time](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Time) | when will this access token expire | False    |
+| Name      | Type                                                                          | Description                        | Required |
+| --------- | ----------------------------------------------------------------------------- | ---------------------------------- | -------- |
+| memo      | string                                                                        | memo for this token                | False    |
+| token     | string                                                                        | token value, minimum length is 64  | True     |
+| rules     | [AccessTokenRule](#accesstokenrule)[]                                         | rules of this token                | True     |
+| creator   | string                                                                        | creator of this token              | True     |
+| expiredAt | \*[metav1.Time](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Time) | when will this access token expire | False    |
 
 ## AccessTokenRule
 
 describe the permission this token has.
 
-| Name      | Type                                                         | Description                        | Required |
-| ---- | ---- | ---- | ---- |
-| verb | [AccessTokenVerb](#accessTokenVerb) | what this token can do | True |
-| namespace | string | namespace this rule has effect on, value `*` means all namespaces. | True |
-| kind | string | kind of resource this rule has effect on, e.g. Kalm's Component, value `*` means all kinds of resources. | True |
-| name | string | name of resource this rule has effect on, value `*` means all resources of the given `kind`. | True |
+| Name      | Type                                | Description                                                                                              | Required |
+| --------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------- | -------- |
+| verb      | [AccessTokenVerb](#accessTokenVerb) | what this token can do                                                                                   | True     |
+| namespace | string                              | namespace this rule has effect on, value `*` means all namespaces.                                       | True     |
+| kind      | string                              | kind of resource this rule has effect on, e.g. Kalm's Component, value `*` means all kinds of resources. | True     |
+| name      | string                              | name of resource this rule has effect on, value `*` means all resources of the given `kind`.             | True     |
 
 ## AccessTokenVerb
 
@@ -40,4 +60,4 @@ describe the permission this token has.
 | Name       | Type | Description                                       |
 | ---------- | ---- | ------------------------------------------------- |
 | lastUsedAt | int  | timestamp that this token last been used at.      |
-| usedCount  | int  | count of how many times this token has been used. |
+| usedCount  | int  | count of how many times this token has been used. |

docs/crd/acme-server.mdx

@@ -2,17 +2,30 @@
 title: ACME Server
 ---
 
+`ACMEServer` defines the ACMEDNS server.
+
+For example, a typical definition of ACMEServer for Kalm-Cloud cluster would look as follows:
+
+```yaml
+apiVersion: core.kalm.dev/v1alpha1
+kind: ACMEServer
+metadata:
+  name: acme-server
+spec:
+  acmeDomain: acme.example-cluster.clusters.kalm-dns.com
+  nsDomain: ns-acme.example-cluster.clusters.kalm-dns.com
+```
+
 ## ACMEServer
 
-|  Field    |    Type  | Description | Required |
-| ---- | ---- | ---- | ---- |
-| acmeDomain | string | sub-domains of this will server TXT records for DNS01 challenge | True |
-| nsDomain | string | the NameServer domain | True |
+| Field      | Type   | Description                                                     | Required |
+| ---------- | ------ | --------------------------------------------------------------- | -------- |
+| acmeDomain | string | sub-domains of this will server TXT records for DNS01 challenge | True     |
+| nsDomain   | string | the NameServer domain                                           | True     |
 
 ## ACMEServerStatus
 
-|  Field    |    Type  | Description |
-| ---- | ---- | ---- |
-| ready | bool | whether this ACME-Server is up running. |
-| ipForNameServer | string | ip for this name server |
-
+| Field           | Type   | Description                             |
+| --------------- | ------ | --------------------------------------- |
+| ready           | bool   | whether this ACME-Server is up running. |
+| ipForNameServer | string | ip for this name server                 |