Skip to content

Commit

Permalink
Fix typos
Browse files Browse the repository at this point in the history
  • Loading branch information
@minac
minac committed Feb 5, 2020
1 parent a20e745 commit 0a64778
Show file tree
Hide file tree
Showing 21 changed files with 212 additions and 216 deletions.
54 changes: 27 additions & 27 deletions allocation-api.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Kubecost exposes multiple APIs to obtain cost, resource allocation, and utilization data. Below is documentation on two options: the cost model API and aggregated cost model API.
Kubecost exposes multiple APIs to obtain cost, resource allocation, and utilization data. Below is documentation on two options: the cost model API and aggregated cost model API.

# Cost model API

Expand All @@ -12,7 +12,7 @@ Here's an example use:

API parameters include the following:

* `timeWindow` dictates the applicable window for measuring cost metrics. Supported units are d, h, and m.
* `timeWindow` dictates the applicable window for measuring cost metrics. Supported units are d, h, and m.
* `offset` shifts timeWindow backwards relative to the current time. Supported units are d, h, and m.

This API returns a set of JSON elements in this format:
Expand All @@ -35,50 +35,50 @@ This API returns a set of JSON elements in this format:
ramreq: [{timestamp: 1567531940, value: 55000000}]
ramused: [{timestamp: 1567531940, value: 19463457.32}]
services: ["cost-model"]
}
}
```
<a name="optional-params"></a>
Optional request parameters include the following:
<a name="optional-params"></a>
Optional request parameters include the following:

Field | Description
--------- | -----------
Field | Description
--------- | -----------
`filterFields` | Blacklist of fields to be filtered from response. For example, appending `&filterFields=cpuused,cpureq,ramreq,ramused` will remove request and usage data.
`namespace` | Filter results by namespace. For example, appending `&namespace=kubecost` only returns data for the `kubecost` namespace


# Aggregated cost model API

The aggregated cost model API retrieves data similiar to the Kubecost Allocation frontend view (e.g. cost by namespace, label, deployment and more) and is available at the following endpoint:
The aggregated cost model API retrieves data similar to the Kubecost Allocation frontend view (e.g. cost by namespace, label, deployment and more) and is available at the following endpoint:

`http://<kubecost-address>/model/aggregatedCostModel`

Here are example uses:

* `http://localhost:9090/model/aggregatedCostModel?window=1d&aggregation=namespace`
* `http://localhost:9090/model/aggregatedCostModel?window=1d&aggregation=namespace`
* `http://localhost:9090/model/aggregatedCostModel?window=1d&aggregation=label&aggregationSubfield=product`
* `http://localhost:9090/model/aggregatedCostModel?window=1d&aggregation=namespace&sharedNamespaces=kube-system`

API parameters include the following:

* `window` dictates the applicable window for measuring cost metrics. Supported units are d, h, m, and s.
* `offset` (optional) shifts window backwards from current time. Supported units are d, h, m, and s.
* `aggregation` is the field used to consolidate cost model data. Supported types are cluster, namespace, deployment, service, and label.
* `window` dictates the applicable window for measuring cost metrics. Supported units are d, h, m, and s.
* `offset` (optional) shifts window backwards from current time. Supported units are d, h, m, and s.
* `aggregation` is the field used to consolidate cost model data. Supported types are cluster, namespace, deployment, service, and label.
* `aggregationSubfield` used for aggregation types that require sub fields, e.g. aggregation type equals `label` and the value of the label (aggregationSubfield) equals `app`.
* `allocateIdle` (optional) when set to `true` applies the cost of all idle compute resources to tenants, default `false`.
* `sharedNamespaces` (optional) provide a comma separated list of namespaces (e.g. kube-system) to be allocated to other tenants. These resources are evenly allocated to other tenants as `sharedCost`.
* `sharedLabelNames` (optional) provide a comma separated list of kubernetes labels (e.g. app) to be allocated to other tenants. Must provide corresponding set of label values in `sharedLabelValues`.
* `sharedLabelValues` (optional) label value (e.g. prometheus) associated with `sharedLabelNames` parameter.
* `sharedNamespaces` (optional) provide a comma-separated list of namespaces (e.g. kube-system) to be allocated to other tenants. These resources are evenly allocated to other tenants as `sharedCost`.
* `sharedLabelNames` (optional) provide a comma-separated list of kubernetes labels (e.g. app) to be allocated to other tenants. Must provide the corresponding set of label values in `sharedLabelValues`.
* `sharedLabelValues` (optional) label value (e.g. prometheus) associated with `sharedLabelNames` parameter.
* `sharedSplit` (optional) Shared costs are split evenly across tenants unless `weighted` is passed for this request parameter. When allocating shared costs on a weighted basis, these expenses are distributed based on the resource costs of the individual pods in the particular aggregation, e.g. namespace.
* `disableCache` this API caches recently fetched data by default. Set this variable to `false` to avoid cache entirely.
* `disableCache` this API caches recently fetched data by default. Set this variable to `false` to avoid cache entirely.

<a name="filter-params"></a>
Optional filter parameters include the following:
<a name="filter-params"></a>
Optional filter parameters include the following:

Filter | Description
--------- | -----------
`cluster` | Filter results by cluster ID. For example, appending `&cluster=cluster-one` will restrict data only to the `cluster-one` cluster. Note: cluster ID is generated from `cluster_id` provided during installation.
Filter | Description
--------- | -----------
`cluster` | Filter results by cluster ID. For example, appending `&cluster=cluster-one` will restrict data only to the `cluster-one` cluster. Note: cluster ID is generated from `cluster_id` provided during installation.
`namespace` | Filter results by namespace. For example, appending `&namespace=kubecost` only returns data for the `kubecost` namespace.
`labels` | Filter results by label. For example, appending `&labels=app%3Dcost-analyzer` only returns data for pods with label `app=cost-analyzer`. CSV list of label values supported. Note that parameters must be url encoded.
`labels` | Filter results by label. For example, appending `&labels=app%3Dcost-analyzer` only returns data for pods with label `app=cost-analyzer`. CSV list of label values supported. Note that parameters must be url encoded.

This API returns a set of JSON objects in this format:

Expand All @@ -87,22 +87,22 @@ This API returns a set of JSON objects in this format:
aggregation: "namespace"
subfields: "" // value(s) of aggregationSubfield parameter
cluster: "cluster-1"
cpuCost: 100.031611
cpuCost: 100.031611
environment: "default" // value of aggregation field
gpuCost: 0
networkCost: 0
pvCost: 10.000000
ramCost: 70.000529625
sharedCost: 0 // value of costs allocated via sharedNamespaces or sharedLabelNames
totalCost: 180.032140625
}
}
```

### Caching Overview
### Caching Overview

Kubecost implements a two-layer caching system for cost allocation metrics. The unaggregated cost model (Layer 1 cache) is pre-cached for commonly used time windows, e.g. 1,2,7 and 30 days. This data is refreshed every ~5 minutes for shorter time windows and up to every 1 hour for long windows, e.g. 30 days. Aggregated cost data (Layer 2 cache) is pre-cached for commonly used aggregatedCostModel API requests, e.g. costs by namespace over the last 7 days. Returning cached data from Layer 1 typically takes < 500ms and Layer 2 < 100ms, not including data transfer times.
Kubecost implements a two-layer caching system for cost allocation metrics. The unaggregated cost model (Layer 1 cache) is pre-cached for commonly used time windows, e.g. 1,2,7 and 30 days. This data is refreshed every ~5 minutes for shorter time windows and up to every 1 hour for long windows, e.g. 30 days. Aggregated cost data (Layer 2 cache) is pre-cached for commonly used aggregatedCostModel API requests, e.g. costs by namespace over the last 7 days. Returning cached data from Layer 1 typically takes < 500ms and Layer 2 < 100ms, not including data transfer times.

When a custom cost model request misses both layers of the Kubecost cache then this request remains in the cache for ~10 minutes. On larger clusters, requests that miss both caching layers can take longer periods, e.g. > 10 seconds.
When a custom cost model request misses both layers of the Kubecost cache then this request remains in the cache for ~10 minutes. On larger clusters, requests that miss both caching layers can take longer periods, e.g. > 10 seconds.


Have questions? Email us at <[email protected]>.
25 changes: 12 additions & 13 deletions architecture.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,23 @@
## Core architecture overview

Below are the major components to the Kubecost helm chart:
1. **Kubecost Cost-Analyzer Pod**
a. Frontend that runs Nginx -- handles routing to Prometheus/Grafana
b. Kubecost server -- backend for API calls

1. **Kubecost Cost-Analyzer Pod**
a. Frontend that runs Nginx -- handles routing to Prometheus/Grafana
b. Kubecost server -- backend for API calls
c. Cost-model -- provides cost allocation calculations and metrics, reads/writes to Prometheus
2. **Cost-Analyzer Jobs** -- used for product alerts & email updates
3. **Prometheus**
a. Prometheus server -- time series data store for cost & health metrics
b. Kube-state-metrics -- provides Kubernetes requests and other core metrics
c. Node-exporter -- provides node-level utilization metrics for right-sizing recommendations and cluster utlization
d. Pushgateway -- ability to push new metrics to Prometheus
e. Alertmanager -- used for custom alerts
3. **Prometheus**
a. Prometheus server -- time-series data store for cost & health metrics
b. Kube-state-metrics -- provides Kubernetes requests and other core metrics
c. Node-exporter -- provides node-level utilization metrics for right-sizing recommendations and cluster utilization
d. Pushgateway -- ability to push new metrics to Prometheus
e. Alertmanager -- used for custom alerts
4. **Network costs** -- optional daemonset for collecting network metrics
5. **Grafana** -- supporting dashboards
5. **Grafana** -- supporting dashboards

Today, the core Kubecost product can be run with just components 1, 3a, 3b, 3c.
Today, the core Kubecost product can be run with just components 1, 3a, 3b, 3c.

See core components on this diagram:

![Architecture Overview](images/arch.png)

16 changes: 8 additions & 8 deletions audit.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
Auditing the cost of workloads can be complex in dynamic Kubernetes environments.
We've created this guide to help you spot check costs and ensure they are calculated as expected.
Auditing the cost of workloads can be complex in dynamic Kubernetes environments.
We've created this guide to help you spot check costs and ensure they are calculated as expected.

1. **Identify a pod or namespace to audit.** In this example we will audit the `default` namespace.
2. **Open Prometheus console.** We recommend going directly to the underlying data in Prometheus for an audit. Complete the following steps to view the console for our bundled Prometheus:
1. **Identify a pod or namespace to audit.** In this example, we will audit the `default` namespace.
2. **Open Prometheus console.** We recommend going directly to the underlying data in Prometheus for an audit. Complete the following steps to view the console for our bundled Prometheus:

* Execute `kubectl port-forward --namespace kubecost service/kubecost-prometheus-server 9003:80`
* Point your browser to <http://localhost:9003>

3. **Verify raw allocation metrics.** Run the following queries and then visit the Prometheus graph tab. Note that allocations are the max of resource requests and usage. Ensure these values are consistent with Kubernetes API and/or cadvisor metrics.
3. **Verify raw allocation metrics.** Run the following queries and then visit the Prometheus graph tab. Note that allocations are the max of resource requests and usage. Ensure these values are consistent with Kubernetes API and/or cAdvisor metrics.

* `container_cpu_allocation{namespace="default"}`
* `container_memory_allocation_bytes{namespace="default"}`
Expand All @@ -18,15 +18,15 @@ We've created this guide to help you spot check costs and ensure they are calcul
* `node_ram_hourly_cost * 730`
* `node_total_hourly_cost * 730`
* `kube_node_status_capacity_cpu_cores * on(node) group_left() node_cpu_hourly_cost * 730 + kube_node_status_capacity_memory_bytes * on(node) group_left() node_ram_hourly_cost * 730 / 1024 / 1024 / 1024`

**Note:** Prometheus values do not account for sustained use, custom prices, or other discounts applied in Settings.

5. **Calculate total resource costs.** Multiply the previously audited allocation by the previously audited price.
5. **Calculate total resource costs.** Multiply the previously audited allocation by the previously audited price.

* `container_cpu_allocation{namespace="default"} * on(instance) group_left() node_cpu_hourly_cost * 730`
* `container_memory_allocation_bytes{namespace="default"} / 1024 / 1024 / 1024 * on(instance) group_left() node_ram_hourly_cost * 730`

6. **Confirm consistency with monthly Allocation view.** Visit the Allocation tab in the Kubecost product. Filter by `default ` namespace. Select `monthly run rate` by `pod` then view the time series chart to confirm the values in the previous step are consistent.
6. **Confirm consistency with monthly Allocation view.** Visit the Allocation tab in the Kubecost product. Filter by `default ` namespace. Select `monthly run rate` by `pod` then view the time series chart to confirm the values in the previous step are consistent.

![Timeseries graph](images/audit-graph.png)

Expand Down
10 changes: 5 additions & 5 deletions availability-tiers.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
Availability Tiers impact capacity recommendations, health ratings and more in the Kubecost product. As an example, production jobs receive higher resource request recommendations than dev workloads. Another example is health scores for high availability workloads are heavily penalized for not having multiple replicas availabile.
Availability Tiers impact capacity recommendations, health ratings and more in the Kubecost product. As an example, production jobs receive higher resource request recommendations than dev workloads. Another example is health scores for high availability workloads are heavily penalized for not having multiple replicas available.

Today our product supports the following tiers:


Tier | Priority | Default
--------- | ----------- | -------
`Highly Available` or `Critical` | 0 | If true, recommendations and health scores heavily prioritize availability. This is the default tier if none is supplied.
`Production` | 1 | Intended for production jobs that are not necessarily mission critical.
`Staging` or `Dev` | 2 | Meant for experimental or development resources. Redundancy or availability is not a high priority.
`Highly Available` or `Critical` | 0 | If true, recommendations and health scores heavily prioritize availability. This is the default tier if none is supplied.
`Production` | 1 | Intended for production jobs that are not necessarily mission-critical.
`Staging` or `Dev` | 2 | Meant for experimental or development resources. Redundancy or availability is not a high priority.

To apply a namespace tier, add a `tier` namespace label to reflect the desired value.
To apply a namespace tier, add a `tier` namespace label to reflect the desired value.

Have questions or feedback? Contact us at <[email protected]>.
4 changes: 2 additions & 2 deletions aws-out-of-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ To access billing data in Athena tables, and to enable other Kubecost functional
*We recommend [kiam](https://github.com/uswitch/kiam) as a solution for adding IAM credentials directly to the Kubecost pod(s).*

### Cost and Usage Permissions Policy
The below policy is designed to provide Kubecost least-priviledge access to AWS Cost and Usage data.
The below policy is designed to provide Kubecost least-privilege access to AWS Cost and Usage data.

Validate the following resource names in the below IAM policy before applying to your account:
* `"Sid": "ReadAccessToAthenaCurDataViaGlue"`: Validate the `database` and `table` ARNs listed. If you used the AWS managed deployment, as described in Step #4, this should already be set correctly. If you set up the Cost and Usage report to Athena flow manually, you may need to adjust this value.
Expand Down Expand Up @@ -196,4 +196,4 @@ Visit the Kubecost Settings page to provide the AWS access credentials and Athen
## Having issues?

* You may need to upgrade your AWS Glue if you are running an old version https://docs.aws.amazon.com/athena/latest/ug/glue-upgrade.html
* Visit the Allocation view in the Kubecost product. If external costs are not shown, open your browser's Developer Tools > Console to see any reported errors.
* Visit the Allocation view in the Kubecost product. If external costs are not shown, open your browser's Developer Tools > Console to see any reported errors.
2 changes: 1 addition & 1 deletion aws-service-account-thanos.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ In order to create an AWS IAM policy for use with Thanos:

&nbsp;&nbsp;6.&nbsp;Provide a User name (e.g. `kubecost-thanos-service-account`) and select `Programmatic access`

&nbsp;&nbsp;7.&nbsp;Select Attach existing policies directly, search for the policy name provided in step 4, and then create user.
&nbsp;&nbsp;7.&nbsp;Select Attach existing policies directly, search for the policy name provided in step 4, and then create the user.

![image](/attach-existing.png)

Expand Down
4 changes: 2 additions & 2 deletions bug-report.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Capture a bug report

The Kubecost bug report feature captures relevent product configuration data and logs to debug an outstanding issue.
The Kubecost bug report feature captures relevant product configuration data and logs to debug an outstanding issue.
To capture a bug report: visit __Settings__, scroll to the bottom, and select __CAPTURE BUG REPORT__.

![Bug report button in setings](images/bug-report.png)


We recommend sharing a bug report directly with our team and not distributing broadly becuase log data is included.
We recommend sharing a bug report directly with our team and not distributing broadly because log data is included.

__Note:__ the bug report feature requires namespace logs access, which is granted by default in Kubecost v1.51.2.
Loading

0 comments on commit 0a64778

Please sign in to comment.