From 0dc9efb2602549dfa6d24469149768ca5d8f5d9c Mon Sep 17 00:00:00 2001 From: Hardik Dodiya Date: Thu, 21 Nov 2024 10:30:43 +0000 Subject: [PATCH] Add initial documentation with with mkdocs --- .github/workflows/publish_docs.yaml | 23 + .reuse/dep5 | 1 + Makefile | 24 + api/v1alpha1/doc.go | 7 + docs/Dockerfile | 14 + docs/README.md | 51 ++ docs/api-reference/api.md | 587 ++++++++++++++++++++++++ docs/architecture.md | 24 + docs/concepts/httpbootconfiguration.md | 0 docs/concepts/ipxebootconfiguration.md | 0 docs/development/dev_docs.md | 15 + docs/requirements.txt | 1 + hack/api-reference/config.json | 32 ++ hack/api-reference/template/members.tpl | 48 ++ hack/api-reference/template/pkg.tpl | 48 ++ hack/api-reference/template/type.tpl | 81 ++++ mkdocs.yml | 63 +++ 17 files changed, 1019 insertions(+) create mode 100644 .github/workflows/publish_docs.yaml create mode 100644 api/v1alpha1/doc.go create mode 100644 docs/Dockerfile create mode 100644 docs/README.md create mode 100644 docs/api-reference/api.md create mode 100644 docs/architecture.md create mode 100644 docs/concepts/httpbootconfiguration.md create mode 100644 docs/concepts/ipxebootconfiguration.md create mode 100644 docs/development/dev_docs.md create mode 100644 docs/requirements.txt create mode 100644 hack/api-reference/config.json create mode 100644 hack/api-reference/template/members.tpl create mode 100644 hack/api-reference/template/pkg.tpl create mode 100644 hack/api-reference/template/type.tpl create mode 100644 mkdocs.yml diff --git a/.github/workflows/publish_docs.yaml b/.github/workflows/publish_docs.yaml new file mode 100644 index 0000000..fdb17b3 --- /dev/null +++ b/.github/workflows/publish_docs.yaml @@ -0,0 +1,23 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: [ main ] + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout main + uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: 'pypy3.9' + - uses: actions/cache@v4 + with: + key: ${{ github.ref }} + path: .cache + - name: Deploy docs + uses: afritzler/mkdocs-gh-pages-action@main + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/.reuse/dep5 b/.reuse/dep5 index 2d17e7d..4d2cb10 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -27,6 +27,7 @@ Files: test/* CONTRIBUTING.md PROJECT + mkdocs.yml .dockerignore .golangci.yml Copyright: 2024 SAP SE or an SAP affiliate company and IronCore contributors diff --git a/Makefile b/Makefile index 4198fb7..4c6a3f8 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,9 @@ IMG ?= controller:latest # ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary. ENVTEST_K8S_VERSION = 1.31.0 +# Docker image name for the mkdocs based local development setup +IMAGE=ironcore-dev/boot-operator-docs + # Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set) ifeq (,$(shell go env GOBIN)) GOBIN=$(shell go env GOPATH)/bin @@ -171,6 +174,7 @@ ENVTEST ?= $(LOCALBIN)/setup-envtest-$(ENVTEST_VERSION) GOLANGCI_LINT = $(LOCALBIN)/golangci-lint-$(GOLANGCI_LINT_VERSION) ADDLICENSE ?= $(LOCALBIN)/addlicense GOIMPORTS ?= $(LOCALBIN)/goimports-$(GOIMPORTS_VERSION) +GEN_CRD_API_REFERENCE_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs-$(GEN_CRD_API_REFERENCE_DOCS_VERSION) ## Tool Versions KUSTOMIZE_VERSION ?= v5.3.0 @@ -179,6 +183,7 @@ ENVTEST_VERSION ?= latest GOLANGCI_LINT_VERSION ?= v1.61.0 ADDLICENSE_VERSION ?= v1.1.1 GOIMPORTS_VERSION ?= v0.26.0 +GEN_CRD_API_REFERENCE_DOCS_VERSION ?= v0.3.0 .PHONY: kustomize kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary. @@ -200,6 +205,16 @@ golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary. $(GOLANGCI_LINT): $(LOCALBIN) $(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/cmd/golangci-lint,${GOLANGCI_LINT_VERSION}) + +.PHONY: startdocs +startdocs: ## Start the local mkdocs based development environment. + docker build -t $(IMAGE) -f docs/Dockerfile . --load + docker run -p 8000:8000 -v `pwd`/:/docs $(IMAGE) + +.PHONY: cleandocs +cleandocs: ## Remove all local mkdocs Docker images (cleanup). + docker container prune --force --filter "label=project=boot_operator" + .PHONY: addlicense addlicense: $(ADDLICENSE) ## Download addlicense locally if necessary. $(ADDLICENSE): $(LOCALBIN) @@ -210,6 +225,15 @@ goimports: $(GOIMPORTS) ## Download goimports locally if necessary. $(GOIMPORTS): $(LOCALBIN) $(call go-install-tool,$(GOIMPORTS),golang.org/x/tools/cmd/goimports,$(GOIMPORTS_VERSION)) +.PHONY: docs +docs: gen-crd-api-reference-docs ## Run go generate to generate API reference documentation. + $(GEN_CRD_API_REFERENCE_DOCS) -api-dir ./api/v1alpha1 -config ./hack/api-reference/config.json -template-dir ./hack/api-reference/template -out-file ./docs/api-reference/api.md + +.PHONY: gen-crd-api-reference-docs +gen-crd-api-reference-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Download gen-crd-api-reference-docs locally if necessary. +$(GEN_CRD_API_REFERENCE_DOCS): $(LOCALBIN) + $(call go-install-tool,$(GEN_CRD_API_REFERENCE_DOCS),github.com/ahmetb/gen-crd-api-reference-docs,$(GEN_CRD_API_REFERENCE_DOCS_VERSION)) + # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist # $1 - target path with name of binary (ideally with version) # $2 - package url which can be installed diff --git a/api/v1alpha1/doc.go b/api/v1alpha1/doc.go new file mode 100644 index 0000000..91165b2 --- /dev/null +++ b/api/v1alpha1/doc.go @@ -0,0 +1,7 @@ +// SPDX-FileCopyrightText: 2024 SAP SE or an SAP affiliate company and IronCore contributors +// SPDX-License-Identifier: Apache-2.0 + +// Package v1alpha1 contains API Schema definitions for the settings.gardener.cloud API group +// +groupName=metal.ironcore.dev +// +kubebuilder:object:generate=true +package v1alpha1 diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..e321554 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,14 @@ +FROM squidfunk/mkdocs-material:latest + +LABEL project=boot_operator + +WORKDIR /docs + +COPY docs/requirements.txt requirements.txt +RUN pip install --no-cache-dir -r requirements.txt + +EXPOSE 8000 + +# Start development server by default +ENTRYPOINT ["mkdocs"] +CMD ["serve", "--dev-addr=0.0.0.0:8000"] \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f56d72b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,51 @@ +# Metal-Operator Documentation + +**Welcome to the Metal-Operator Documentation!** + +The `metal-operator` is a Kubernetes-native operator, part of the IronCore open-source project, designed for robust bare metal infrastructure management. By leveraging Baseboard Management Controllers (BMCs) and the Redfish API, `metal-operator` enables streamlined and automated server discovery, provisioning, and lifecycle management. Using the Kubernetes Controller pattern, `metal-operator` provides a CRD-based operational model that standardizes bare metal management across different hardware environments. Integration with vendor-specific tooling is also possible for enhanced functionality when needed. + +--- + +## Key Features + +### 1. **Discover and Onboard Bare Metal Servers** +- Automatically detect and register bare metal servers through BMCs and the Redfish API. +- Efficiently gather hardware specs, network configurations, and initial health checks directly from BMC interfaces. + +### 2. **Provision Software on Bare Metal Servers** +- Deploy and configure software on registered servers using BMC interactions and standardized provisioning workflows. +- Support for dynamic software configuration and Redfish API-based management for consistent, vendor-neutral provisioning. + +### 3. **Manage Server Reservations** +- Reserve specific bare metal resources based on workload needs. +- Prevent resource conflicts by managing reservations via Kubernetes-native CRDs, ensuring that workloads align with available hardware resources. + +### 4. **Perform Day 2 Operations** +- Utilize the Redfish API to manage BIOS, firmware, and driver updates. +- Automate ongoing maintenance tasks and operational workflows to maintain infrastructure resilience and uptime. + +### 5. **Decommission and Maintain Faulty Servers** +- Decommission servers via BMC controls for clean removal from active pools. +- Schedule and perform maintenance tasks with BMC data to optimize uptime and maintain hardware reliability. + +--- + +## How It Works + +The `metal-operator` relies on **BMCs and the Redfish API** to handle bare metal server management tasks. Through a CRD-based operational model, `metal-operator` provides Kubernetes-native management of bare metal infrastructure, enabling consistent, vendor-neutral interactions. + +### Core Components +- **Custom Resources (CRs)**: Extend Kubernetes to manage server configurations, reservations, and operational workflows. +- **Controllers**: Automate lifecycle management through Redfish-enabled interactions, from provisioning to decommissioning. +- **Reconcilers**: Ensure the desired state matches the actual state by continuously monitoring hardware via BMC integrations. + +### Architecture Overview + +1. **Discovery**: Register new bare metal servers through BMCs and Redfish API, creating CRDs for streamlined management. +2. **Provisioning**: Apply software images and configurations using Redfish API, based on templates or custom configurations. +3. **Operations**: Execute BIOS, firmware updates, and other maintenance tasks through standardized workflows. +4. **Decommissioning**: Safely remove or maintain servers using Redfish and BMC controls, marking them for reuse or retirement as needed. + +--- + +The `metal-operator` is a core component of the IronCore project, designed to simplify and automate bare metal management across various hardware environments using BMC and Redfish API integrations. Expect continuous updates to expand capabilities and enhance usability. \ No newline at end of file diff --git a/docs/api-reference/api.md b/docs/api-reference/api.md new file mode 100644 index 0000000..61c4a2c --- /dev/null +++ b/docs/api-reference/api.md @@ -0,0 +1,587 @@ +

Packages:

+ +

metal.ironcore.dev/v1alpha1

+
+

Package v1alpha1 contains API Schema definitions for the settings.gardener.cloud API group

+
+Resource Types: + +

HTTPBootConfig +

+
+

HTTPBootConfig is the Schema for the httpbootconfigs API

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +metal.ironcore.dev/v1alpha1 + +
+kind
+string +		HTTPBootConfig
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +HTTPBootConfigSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + +
+systemUUID
+ +string + +		 +
+ignitionSecretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +
+systemIPs
+ +[]string + +		 +
+ukiURL
+ +string + +		 +
+
+status
+ + +HTTPBootConfigStatus + + +		 +
+

IPXEBootConfig +

+
+

IPXEBootConfig is the Schema for the ipxebootconfigs API

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +metal.ironcore.dev/v1alpha1 + +
+kind
+string +		IPXEBootConfig
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +IPXEBootConfigSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+systemUUID
+ +string + +		 +

Important: Run “make” to regenerate code after modifying this file

+
+systemIPs
+ +[]string + +		 +
+image
+ +string + +		 +

TODO: remove image as this is not needed

+
+kernelURL
+ +string + +		 +
+initrdURL
+ +string + +		 +
+squashfsURL
+ +string + +		 +
+ipxeServerURL
+ +string + +		 +

TODO: remove later

+
+ignitionSecretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +
+ipxeScriptSecretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +
+
+status
+ + +IPXEBootConfigStatus + + +		 +
+

HTTPBootConfigSpec +

+

+(Appears on:HTTPBootConfig) +

+
+

HTTPBootConfigSpec defines the desired state of HTTPBootConfig

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+systemUUID
+ +string + +		 +
+ignitionSecretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +
+systemIPs
+ +[]string + +		 +
+ukiURL
+ +string + +		 +
+

HTTPBootConfigState +(string alias)

+

+(Appears on:HTTPBootConfigStatus) +

+
+
+ + + + + + + + + + + + + + +
ValueDescription

"Error"

"Pending"

"Ready"

+

HTTPBootConfigStatus +

+

+(Appears on:HTTPBootConfig) +

+
+

HTTPBootConfigStatus defines the observed state of HTTPBootConfig

+
+ + + + + + + + + + + + + +
FieldDescription
+state
+ + +HTTPBootConfigState + + +		 +
+

IPXEBootConfigSpec +

+

+(Appears on:IPXEBootConfig) +

+
+

IPXEBootConfigSpec defines the desired state of IPXEBootConfig

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+systemUUID
+ +string + +		 +

Important: Run “make” to regenerate code after modifying this file

+
+systemIPs
+ +[]string + +		 +
+image
+ +string + +		 +

TODO: remove image as this is not needed

+
+kernelURL
+ +string + +		 +
+initrdURL
+ +string + +		 +
+squashfsURL
+ +string + +		 +
+ipxeServerURL
+ +string + +		 +

TODO: remove later

+
+ignitionSecretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +
+ipxeScriptSecretRef
+ + +Kubernetes core/v1.LocalObjectReference + + +		 +
+

IPXEBootConfigState +(string alias)

+

+(Appears on:IPXEBootConfigStatus) +

+
+
+ + + + + + + + + + + + + + +
ValueDescription

"Error"

"Pending"

"Ready"

+

IPXEBootConfigStatus +

+

+(Appears on:IPXEBootConfig) +

+
+

IPXEBootConfigStatus defines the observed state of IPXEBootConfig

+
+ + + + + + + + + + + + + +
FieldDescription
+state
+ + +IPXEBootConfigState + + +		 +

Important: Run “make” to regenerate code after modifying this file

+
+
+

+Generated with gen-crd-api-reference-docs +

diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..b5c682a --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,24 @@ +# Boot-Operator Architectural Description + +## Architectural Diagram + +TBD + +## Key Components + +### 1. Custom Resource Definitions (CRDs) + +- [**IPXEBootConfiguration**](concepts/ipxebootconfig.md): TBD +- [**HTTPBootConfiguration**](concepts/httpbootconfig.md): TBD + +### 2. Controllers + +TBD + +## Workflow Summary + +TBD + +## Architectural Benefits + +TBD \ No newline at end of file diff --git a/docs/concepts/httpbootconfiguration.md b/docs/concepts/httpbootconfiguration.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/concepts/ipxebootconfiguration.md b/docs/concepts/ipxebootconfiguration.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/development/dev_docs.md b/docs/development/dev_docs.md new file mode 100644 index 0000000..b482c71 --- /dev/null +++ b/docs/development/dev_docs.md @@ -0,0 +1,15 @@ +# metal-operator documentation + +## Local dev setup + +You can run the documentation via: + +```shell +make startdocs +``` + +You can remove the `mkdocs` container image by running: + +```shell +make cleandocs +``` \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b5a29e7 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +# your mkdocs plugins go here \ No newline at end of file diff --git a/hack/api-reference/config.json b/hack/api-reference/config.json new file mode 100644 index 0000000..80e79d8 --- /dev/null +++ b/hack/api-reference/config.json @@ -0,0 +1,32 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^net/netip", + "docsURLTemplate": "https://pkg.go.dev/net/netip#{{.TypeIdentifier}}" + }, + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/api/resource", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#{{.TypeIdentifier}}" + }, + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/types", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/types#{{.TypeIdentifier}}" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/api-reference/template/members.tpl b/hack/api-reference/template/members.tpl new file mode 100644 index 0000000..a529c67 --- /dev/null +++ b/hack/api-reference/template/members.tpl @@ -0,0 +1,48 @@ +{{ define "members" }} + +{{ range .Members }} +{{ if not (hiddenMember .)}} + + + {{ fieldName . }}
+ + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

+ (Members of {{ fieldName . }} are embedded into this type.) +

+ {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") }} +
+
+ + {{ template "members" .Type }} +
+ {{ end }} + + +{{ end }} +{{ end }} + +{{ end }} diff --git a/hack/api-reference/template/pkg.tpl b/hack/api-reference/template/pkg.tpl new file mode 100644 index 0000000..14eae29 --- /dev/null +++ b/hack/api-reference/template/pkg.tpl @@ -0,0 +1,48 @@ +{{ define "packages" }} + +{{ with .packages}} +

Packages:

+ +{{ end}} + +{{ range .packages }} +

+ {{- packageDisplayName . -}} +

+ + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} +
+ {{ safe (renderComments .) }} +
+ {{ end }} + {{ end }} + + Resource Types: + + + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} +
+{{ end }} + +

+ Generated with gen-crd-api-reference-docs +

+ +{{ end }} diff --git a/hack/api-reference/template/type.tpl b/hack/api-reference/template/type.tpl new file mode 100644 index 0000000..8f0d66b --- /dev/null +++ b/hack/api-reference/template/type.tpl @@ -0,0 +1,81 @@ +{{ define "type" }} + +

+ {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

+{{ with (typeReferences .) }} +

+ (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{- $prev = . -}} + {{ typeDisplayName . }} + {{- end -}} + ) +

+{{ end }} + +
+ {{ safe (renderComments .CommentLines) }} +
+ +{{ with (constantsOfType .) }} + + + + + + + + + {{- range . -}} + + {{- /* + renderComments implicitly creates a

element, so we + add one to the display name as well to make the contents + of the two cells align evenly. + */ -}} +

+ + + {{- end -}} + +
ValueDescription

{{ typeDisplayName . }}

{{ safe (renderComments .CommentLines) }}
+{{ end }} + +{{ if .Members }} + + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" .}} + +
FieldDescription
+ apiVersion
+ string		 + + {{apiGroup .}} + +
+ kind
+ string + 		{{.Name.Name}}
+{{ end }} + +{{ end }} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..ef0e7a6 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,63 @@ +site_name: IronCore / Boot Operator +repo_url: https://github.com/ironcore-dev/boot-operator/ +edit_uri: edit/main/docs/ +theme: + icon: + repo: fontawesome/brands/github + features: + - navigation.instant + - navigation.tracking + - navigation.expand + - navigation.indexes + - navigation.top + name: material + logo: https://raw.githubusercontent.com/ironcore-dev/ironcore/main/docs/assets/logo.svg + favicon: https://raw.githubusercontent.com/ironcore-dev/ironcore/main/docs/assets/favicon/favicon.ico + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: white + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + toggle: + icon: material/weather-sunny + name: Switch to light mode + font: + text: 'Work Sans' + +plugins: +- search + +markdown_extensions: +- pymdownx.highlight +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format +- pymdownx.snippets +- codehilite +- admonition +- abbr +- toc: + permalink: true + +nav: +- Home: README.md +- Architecture: architecture.md +- Concepts: + - IPXEBootConfiguration: concepts/ipxebootconfig.yaml + - HTTPBootConfiguration: concepts/httpbootconfig.yaml +- Development Guide: + - Local Setup: development/dev_setup.md + - Documentation: development/dev_docs.md +- API Reference: api-reference/api.md + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/ironcore-dev/boot-operator \ No newline at end of file